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PREFACE: ORIGINS OF APL 


APL is the outgrowth of proposals made during 
the 1950’s by Dr. Kenneth E. Iverson, then at 
Harvard University. The language was first des- 
cribed in detail in his book A Programming Lan- 
guage, published by Wiley in 1962. In 1960 Iver- 
son joined the IBM Research Center in Yorktown 
Heights, New York, and there, in collaboration 
with Adin D. Falkoff, continued to develop propo- 
sals for the language. During the mid 1960’s, 
several experimental computer systems were writ- 
ten to execute what was then called “Iverson nota- 
tion.” In 1968 IBM released two of these to the 
public: APL\1130, a stand alone version for the 
IBM 1130 computer, and APL\360, the first com- 
mercially distributed time-sharing implementation 
of the language. APL\360 was primarily the work 
of three people: Lawrence M. Breed and Richard 
H. Lathwell of IBM, and Roger D. Moore of IP. 
Sharp Associates. For their work in its develop- 
ment, the three shared the Grace Murray Hopper 
award for 1973; the awards committee of the As- 
sociation for Computing Machinery cited them for 
setting “new standards of performance, reliability 
and responsiveness in a time-sharing system.” 


Following the release of APL\360, a number of 
companies began to offer APL commercially. 1.P. 
Sharp Associates was one of the first to offer such 
a service, starting in 1969. Soon after the first 
offering from IBM, systems for APL were 
produced by several other computer manufactur- 
ers. Companies specializing in the use of APL 
began to develop extensions, such as the dedicated 
file system for APL developed jointly by Scientific 
Time-Sharing Corporation and I.P. Sharp As- 
sociates during 1969 and 1970; their joint offering 
of APL\360 with files was known as APL PLUS. 
Since then, the two companies have continued 
separately to add enhancements to their respective 
APL systems. 


By now, one or another form of APL service has 
become widespread, and there are many im- 
plementations on many types of equipment. There 


has emerged an “APL community” of people in 
many countries who in one way or another work 
with APL, and several international conferences 
have been devoted to the language and its applica- 
tions. The ACM now includes a special interest 
group on APL, and puts out a publication, APL 
Quote Quad, devoted to APL. 


Despite the variety of its adherents and implemen- 
tations, there is a general consensus among mem- 
bers of the APL community on the central con- 
cepts and definitions of the language. Builders of 
APL systems tend to distinguish the “language 
Proper” from the various ancillary services (such 
as file processors) which are considered to be out- 
side the core of the language. It is the intention 
of I.P. Sharp Associates that SHARP APL remain 
consistent with the APL language as it is described 
in publications such as IBM’s manual APL Lan- 
guage (publication GC26-3847). On the other 
hand, I.P. Sharp Associates has introduced en- 
hancements that provide facilities not otherwise 
available, and expects to continue to do so. Exten- 
sions have been included by adding new “distin- 
guished names” (that is, names beginning with the 
symbol 0), but without altering either the fun- 
damental syntax of APL or the meaning of any 
of its primitive symbols. The principal enhance- 
ments evident in this manual concern direct access 
to files, a formatting primitive, batch APL, the 


“package” data type, and event trapping. 
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FOREWORD: 


WHO SHOULD READ 
THIS MANUAL, 
AND HOW 





This manual should answer questions about the 
use of SHARP APL for a wide range of people. 
Its intended audience includes both the occasional 
user of APL and the professional programmer, 
and people at various levels of APL expertise in 
between. The section called “Outline of Services 
Offered by the SHARP APL System” may also 
be useful to the manager of a group contemplating 
the use of SHARP APL or the installation of a 
SHARP APL system. 


You should think of this manual as a place in 
which to look things up. When you have a ques- 
tion about how something works, first consult the 
table of contents or the index. Sometimes you'll 
find the same topic discussed in more than one 
place, depending on the other topics to which it 
is related. 


This manual is not a course—although you might 
find it a useful companion while you’re taking one. 
You shouldn’t try to read it straight through from 
beginning to end (except perhaps to skim it for 
an impression of what the various chapters con- 
tain). Some chapters (for example, the review of 
APL syntax) will make more sense once you've 
started to feel familiar with APL, and wish to 
review. 


This manual contains a description of each of the 
functions that is primitive (that is, built-in) to 
SHARP APL. The descriptions vary in both for- 
mat and level of detail; functions which may be 
unfamiliar are described in greater detail than 
those with which almost everyone is likely to have 
had experience. Certain topics, such as the use of 
formatting primitives, or techniques for submitting 
batch tasks in SHARP APL, are covered in separ- 
ate publications, and so are here summarized more 
briefly, with a note on where to look for additional 
coverage. Several topics have also been described 
in the series of publications called SHARP APL 
Technical Notes (SATNs, for short), and SATNs 
will continue to be issued as there are new 
developments in SHARP APL. 


FOREWORD: WHO SHOULD READ THIS MANUAL, AND HOW 


While this manual was in preparation, a few users 
expressed the hope that it would explicitly com- 
pare features of SHARP APL with those of other 
APL systems, and make plain any points of differ- 
ence. We hope it will indeed make evident the 
details of SHARP APL. But it doesn’t provide 
comparisons. While sympathizing with the needs 
of those of you who have experience elsewhere, we 
didn’t feel we could or should try to document 
systems other than our own. On the other hand, 
we've tried to make this description of SHARP 
APL sufficiently detailed and precise that you'll 
find it easy to make such comparisons for your- 
selves. 


Finally, this manual is intended to describe what 
SHARP APL is and how it works rather than 
how best to use it. Thus, although the style and 
organization of programs are important issues, this 


isn’t the place to address them. e, 
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OVERVIEW OF SHARP APL 


Introduction 


APL is a powerful, easy-to-use, high-level pro- 
gramming language. The SHARP APL system 
provides a way to carry out work written in APL. 
It also provides other services that support the 
work of many people using the system at the same 
time. 


Characteristics of APL 


The following list is not a description of APL. 
Rather, it’s a summary of some of the features that 
distinguish APL from other languages and account 
for the particular usefulness of APL. 


1. Simple syntax: The same few rules apply to 
all primitive (that is, built-in) functions and to 
all user-defined functions (programs). That 
means that you can use several defined functions 
in a compound expression, just as you can write 
compound expressions involving primitives. A 
statement in a function’s definition may be built 
up from phrases that refer to many other user- 
defined functions. 


2. Modular structure: The definition of one 
function can refer to other user-defined functions. 
That means that definitions can be nested to what- 
ever level you find convenient to provide simple 
top-down organization. Each defined function can 
create its own local environment (that is, condi- 
tions in effect only while it is being executed ). 
Any program can serve as a subroutine to any 
other. 


3. Array orientation: A variable is a named 
collection of data. Unless it’s a special kind of data 
called a “package,” a variable is an array. In prin- 
ciple, an array can have any number of elements, 
arranged along any number of axes. Every data- 
array is self-describing; there are no advance de- 
clarations of the type, structure, or size of an 


array. A function applies automatically to all the 
elements of an array. This may be to each element 
independently (for example, A+B); along a par- 
ticular axis (for example, +/A, sum over the last 
axis of A); to a plane within an array (for exam- 
ple, ABB); or to an entire array. Automatic 
processing of an entire array frequently eliminates 
the need for explicit indexing and iteration that is 
characteristic of many other languages. APL in- 
cludes many primitives for manipulating or des- 
cribing arrays. 


4. Rich set of primitives: The language in- 
cludes a full set of primitive functions selected 
from arithmetic, logic, matrix algebra, number re- 
presentation, trigonometry, and functions for deal- 
ing with arrays. Array primitives include functions 
to report the size and shape of an array, to reshape 
an array, to transpose it, reverse it or rotate it 
along a particular axis, find the locations of par- 
ticular values, or select a sub-array. Each primi- 
tive function is denoted by a symbol; where possi- 
ble, these are the same symbols already in use in 
arithmetic and algebra. There are no reserved 
words in APL, so you can give a variable or a 
function any name whatever. 


5. Convenient defaults: If a result is neither 
stored nor passed to another function, the system 
automatically formats and displays it. 


6. Interpretive execution: APL permits a 
name to take on new meanings dynamically, as 
work proceeds. For this reason, SHARP APL is 
interpretive. That is, each program is stored the 
way it’s written; no decision is made about what 
a name refers to until the moment of execution. 
There is no distinction between “source” and “ob- 
ject” code. Corrections or changes to a program 
may therefore be made after its execution has 
started; this is particularly valuable in “debug- 
ging” new programs. 


7. Rapid application development and easy 
maintenance: Taking advantage of APL’s 
modular structure and simple syntax, programs 
can be made easy to read, easy to understand, easy 
to correct, and easy to modify. It is especially sim- 
ple to build new applications from “building 
blocks” developed earlier, or available from public 
libraries within the system. 


Outline of services offered by the SHARP APL 
system 


SHARP APL permits many users at different 
locations to make use of a large central computer. 
All computation is expressed in APL. As one of 
the users of the APL system, you have the impres- 
sion of exclusive use of an APL machine—except 
that other users may be sharing the same data, and 
any user may make use of public programs or 
data. Each user communicates with APL from a 
terminal; the terminal must be of a type acceptable 
to the system and equipped to display the APL 
character set. However, the terminal is not con- 
sidered part of the system. 


The total service can be divided into the following 
subsystems: 


1. The APL interpreter: The interpreter 
executes programs written in APL. 


2. The APL system: The system includes the 
interpreter and also additional facilities to man- 
age the work of the various users. It provides 
means to: 


a. Maintain a directory of user account num- 
bers. 


b. Accept user sign-ons, and maintain a record 
of work done and charges accrued. 


c. Schedule time-shared work. The system 
devotes a fraction of a second to each of the 
active users in turn. Unless the user load is 
particularly heavy or the calculation you’ve 
requested is particularly large, you seem to 
have the machine’s immediate attention. 


d. Schedule batch APL work. You may request 
that a batch job written in APL be run, 
either to start immediately or at some sub- 
sequent off-peak time. 


e. Manage input/output at the terminals of 
interactive users. 


f. Permit users to enter, display, and edit the 
definitions of functions written in APL. You 
may correct the definition of a function that 
has been interrupted, and resume execution. 


OVERVIEW OF SHARP APL 2 


3 


g. Store and retrieve work of individual users. 


h. Maintain workspaces containing public- 
ly-available packages of programs and/or 
data. 


. The file system: The file system provides 


auxiliary storage for individual user accounts, 
or for public use. The file system is specific to 
SHARP APL in the following ways: 


a. All file operations, including reading, writ- 
ing, creation, deletion, etc., are handled by 
system functions primitive to SHARP APL. 


b. Each component of a file is an APL data 
object; APL data objects are self-describing. 
You can change the size of a file component 
from one time to another, and the various 
components may vary in size from one 
another. 


. Batch facilities: Batch work is charged at a 


lower rate than interactive (immediate execu- 
tion) work. You may request: 


a. Batch APL tasks. 
b. Batch file printing. 


c. Batch file sorting. 


. Communications network: A system of data 


transmission lines and minicomputers gives 
local dial-up access to users in many cities 
around the world. Access may be by either of 
two routes: 


a. The Sharp network. Dialing a telephone 
number in one of the cities on the Sharp 
network connects you directly to the Sharp 
central computer. 


b. An intermediate commercial network. After 
dialing certain commercial networks, you 
may request to be connected to the Sharp 
network. 
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6. System utilities: These are not directly accessi- 


ble to a user, but are used at the central loca- 
tion to support operations of the APL system. 
They include provisions to: 


a. “Back up” stored files and work- 
spaces—that is, to make archive copies that 
can be retrieved in the event that current 
ones are destroyed by hardware failure or 
programming error. 


b. Exchange workspaces with other systems. 

c. Exchange files with other systems (includ- 
ing the ability to convert file formats so that 
data can be exchanged with non-APL 


systems). 


d. Bill you for your use of the system. 


t% 


Chapter 2: 
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Interactive and batch use 


SHARP APL is organized for both batch and in- 
teractive work. The fundamental style of work is 
interactive. 


You use APL from a terminal, (usually your own, 
at your own location). From your terminal, you 
contact the SHARP APL system, usually by tele- 
phone. You announce yourself to the SHARP 
APL system by transmitting your account number 
and password, and thereby start an interactive ses- 
sion. 


While you are connected, the system attempts to 
appear to you as though it were an APL machine, 
serving you exclusively. It accepts instructions 
written in APL, and acts on them immediately. 


Terminals for use with APL: You can use 
SHARP APL from a wide variety of terminals, 
including printing terminals and video display 
units. However, some terminals are more conven- 
iently used than others, and there exist terminals 
that cannot be used at all with APL. If in doubt, 
consult your SHARP APL representative. 


If you’re going to write or display programs writ- 
ten in APL, you will need a terminal equipped 
to produce the APL character set. For terminals 
using an interchangeable print-wheel or type ele- 
ment, this may require no more than inserting the 
appropriate element. But terminals that generate 
video displays or use dot-matrix printing may 
require a built-in capability to form APL charac- 
ters. 


It is helpful to use a terminal whose key tops are 
marked with APL characters, but it’s still possible 
to use one with other key tops. The figure shows 
a keyboard layout commonly used on terminals 
equipped for APL and using the ASCII typewri- 
ter-pairing conventions. 
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Dialogue between user and system: Because 
each entry is acted on at once, a work session at 
a terminal takes on the appearance of a dialogue 
between you and the SHARP APL system. You 
make a line of entry, the system acts on it, you 
make another entry, and so on. When you ask for 
the result of a calculation, the system displays it, 
and then awaits your next entry. The session is 
open-ended, since after each cycle of entry and 
response, you then decide what to do next. Of 
course, you may invoke a function which makes 
a succession of requests for input from the key- 
board, and in that sense begins to manage the 
dialogue. But apart from that, you are in charge, 
and as the system completes work on each entry, 
it is again up to you to decide what you wish to 
ask for next. 


Automatic display of result: When it executes 
an APL statement, the system either stores the 
result (if instructed to do so) or displays it. Unless 
instructed how to display a result, the system au- 
tomatically picks a format. Thus, the “default” 
state of affairs—what happens unless you request 
otherwise—is that results are printed in a format 
provided automatically by the system. For simple 
calculations, this means that all you have to do is 
enter the statement you want executed, and the 
system immediately executes it, formats the result, 
and displays it. 


Distinguishing who typed what: Because work 
normally proceeds as a dialogue, it becomes impor- 
tant (in looking back as a session progresses) to 
distinguish your requests from the system’s re- 
sponses. Except when input is requested by a 
function you’ve invoked, each time it is ready for 
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a new request, the system indents the cursor by 
six spaces, but does not indent its displays. Thus, 
generally speaking, your entries appear indented 
while the system’s responses do not. 


Immediate notification of error: It may hap- 
pen that you enter an instruction that is invalid. 
When the system tries to execute your instruction, 
it discovers that something is wrong. Unless you 
have given advance instructions regarding this con- 
tingency (that is, how to “trap” the error) the 
system immediately suspends execution, and sends 
you a description of the problem. 


Immediate correction of error: If the problem 
is that you mistyped your last request, you may 
now invoke the line editor, correct the instruction, 
and immediately re-enter it. 


If the problem is a misstatement in a defined func- 
tion you may (subject to some restrictions) im- 
mediately edit the offending statement, and resume 
execution. Thus, you can readily fix a great many 
minor errors as you proceed. (Of course when the 
problem is that your underlying method is ill-con- 
ceived, correcting it may require more drastic 
steps. ) 


Invoking batch work from an interactive ses- 
sion 


While working at your terminal, you may give 
instructions regarding a batch task. Those instruc- 
tions cause the system to start work on a batch 
task either immediately or at some subsequent 
ume. 





A batch task uses the same language in the same 
manner as an interactive task. They differ only in 
the amount of interaction that is possible. For that 
reason, a batch task is almost always developed by 
automating what starts out as an interactive task. 


All calculation takes place in your active work- 
space: While you’re working from a terminal, 
the portion of the computer’s storage that is direct- 
ly accessible to you is called your active work- 
space. All the calculation you do takes place in 
your active workspace. Any defined function that 
you use must be present in your active workspace 
while you’re using it, and so must any data 
required to carry out your calculations. You may 
have other storage apart from the active workspace 
(both files and saved workspaces), but they can 
be used only for storage. When you make use of 
what’s stored in them, what you use must be pre- 
sent in your active workspace. 


Each batch task has an active workspace in exactly 
the same way that you do when you work from 


a terminal. a 
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Chapter 3: 


ORGANIZATION 
OF THE 


SHARP APL 


SYSTEM 





Central computing facility 


The system is organized around a single central 
computing facility in which all computation is 
done and all data are stored. For speed and 
reliability, this central facility may well involve 
more than one central computer. Nevertheless, all 
work is under the control of a master program at 
a single location. Minicomputers at various cities 
in the network greatly enhance the reliability of 
communication with the central system, but they’re 
involved only in transmitting data, and not in any 
other aspect of processing it. 


Account numbers 


As a user of the system, you are identified by an 
account number. The system maintains a directo- 
ry of valid numbers, together with the name and 
address of the person or organization to which 
each is assigned. Any work you do at the comput- 
er, and any data you store, is assigned to your 
account number. Any task being done and any set 
of stored data has an explicit owner. 


Tasks 


A session of computing on your behalf is called a 
task. There are three kinds of tasks: 


T-tasks, or terminal tasks 
N-tasks, or non-terminal tasks 
B-tasks, or batch tasks 


A terminal task starts when you sign on at a 
terminal with your account number and password. 
The task consists of all work you do from the time 
you sign on until you sign off. You can have only 
one terminal task at a time. During a terminal 
task, instructions or data that you key from the 
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terminal are acted upon at once. After you see the 
display resulting from a request, you decide what 
to do next. The task thus consists of a dialogue 
between you and the system. 


A non-terminal task is one which is associated 
with a valid account number, but not with a ter- 
minal. It must be started by another task. Work 
on an N-task starts immediately, and runs steadily 
either until it is completed, or until a problem is 
encountered. Then the task is terminated. You 
may have several non-terminal tasks active at once. 


A batch task runs in the same way as a non- 
terminal task. That is, it is associated with a valid 
account number, and, once started, it runs unat- 
tended until its work is completed or it is inter- 
rupted. A batch task differs from a non-terminal 
task principally in its scheduling. Work on it 
begins not immediately but at some later time, 
determined not by the user but by the system’s 
B-task scheduler. If the system interrupts a B-task, 
under some conditions it can restart the task au- 
tomatically. 


Batch tasks are billed at a rate lower than for 
non-terminal tasks, and they in turn at a rate 
lower than for terminal tasks. 


Workspaces 


Each of your active tasks has associated with it a 
workspace. This is called the task’s active work- 
space, to distinguish it from a saved workspace. 
A saved workspace is a snapshot of the active 
workspace saved for later use. 


Each task has exactly one active workspace. The 
maximum size of all workspaces is the same. At 
present, that size is about 256K bytes (that is, 256 
x1024 bytes). 


All computation takes place in your active work- 
space. While a program is being executed, its 
definition must be present in the active workspace; 
any data used by a calculation must be present in 
the workspace; there must be room in the work- 
space for the results and for any partial results 
that may be developed along the way. However, 
you can move programs or data into or out of the 
active workspace as needed; the only things that 
must be present in your active workspace are the 
items that are immediately necessary to a calcula- 
tion. 


Objects stored in a workspace must be named, and 
may be referred to only by name. The system 
keeps track of the meaning of each name in use 
in your active workspace. 


Things in your active workspace are visible only 
to you. The only exception is when you have made 
explicit arrangements to transmit data to another 
workspace, or to a file that’s accessible to others. 


Saved workspaces 


While you’re working at a terminal (that is, at a 
T-task), you can save a duplicate of your active 
workspace. This creates in auxiliary storage a du- 
plicate of your active workspace. Your active 
workspace (and thus the saved duplicate of it) 
contains a list of all the names that are in use in 
the workspace, together with their current mean- 
ings (as functions or as data). The workspace also 
contains the state indicator (or “stack’’), a list of 
all programs whose execution is under way, 
together with the line counter, which shows the 
number of the line within each program now 
being executed. Because the saved version of the 
workspace contains the state indicator and line 
counter, as well as any data and function defini- 
tions involved in the current work, it is possible 
at a later time to “load” the saved workspace (that 
is, bring back a duplicate of it so that it is again 
the active workspace) and to resume work at the 
point where it was halted when the workspace was 
saved. 


A saved workspace belongs to an account number. 
Usually it belongs to the account number of the 
user who saved it. The set of all saved workspaces 
belonging to a particular account is called that 
account’s library. You can ask to see a list of the 
workspaces you have saved in your private library. 
Nobody else can see that list. On the other hand, 
if you were to tell another user your account num- 
ber and the name of a workspace in your private 
library, the person would then be able to use a 
copy of your workspace. But that person wouldn’t 
be able to make any change in the workspace 
saved in your library. In short, other people can 
make use of workspaces you’ve saved, but only if 
you provide them the information they need in 
order to get a duplicate of a workspace of yours. 
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Public workspaces 


Although workspaces saved by one user are ordi- 
narily invisible to another user, it is possible to 
save a workspace not into your own private li- 
brary, but into a public library, where it can be 
seen and used (but not altered) by others. Public 
libraries are given account numbers less than 1000 
(usually as a convenience in keeping related work- 
spaces together). No individual user has an ac- 
count number less than 1000. Any user may get 
a list of the workspaces saved in a public library, 
and may cause a duplicate of a workspace from 
a public library to be made active (“loaded”) on 
his or her behalf. This is one of the mechanisms 
that permit you, as a private user, to make use of 
publicly available programs or data. Public li- 
braries are maintained by people known as the 
system librarians. 


Files 


A file is a collection of data stored independently 
of workspaces. A file has a name, and is associated 





with an account number. A file is made up of 
components. Each component contains a single 
APL data object (that is, a package or an array) 
of any size. The components of a file are not 
named, but referred to by number. You can trans- 
fer one component at a time between your active 
workspace and the file. 


As owner of a file, you may specify which other 
users may have access to the file, and what sort 
of access each of them can have. The file system 
is discussed in Chapter 12, and in detail in a 
separate publication, “SHARP APL File System.” 
System functions for managing files are summar- 
ized in this manual in Chapter 24. 


SHARP APL provides primitive functions for 
creating and deleting files, and for transferring 
data between the active workspace and a file. 


One of the ways a file differs from a workspace 
is that a file may be shared among several users, 
so that, for example, users in different locations 
can simultaneously read and write data in the 
same file. The system also provides a way to 
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“hold” a file, so there won’t be conflicts when 
different users are updating the same file at the 
same time. 


Each component of a file is individually time- 
stamped. The stamp shows who wrote that compo- 
nent, and when. That makes it possible for the 
system utilities to make “back-up” copies of all 
active files on a daily basis, as a safeguard against 
losing data by equipment failure or program error. 


Files may be created so that any user can read 
them. This is a means of making public data 
bases generally available. 


Distinction between the APL language and the 
APL system 


The APL language is an abstract notation for stat- 
ing formulas or procedures. It is abstract in the 
sense that it permits you to say what functions are 
to be applied to data (that is, numbers or charac- 
ters) without having to be concerned with how the 
data are represented or how the functions are 
executed—indeed, without any reference to the 
physical devices that may be used to store the data 
or to carry out the calculations. 


The APL system is the collection of equipment, 
together with the master programs that control it, 
that provide the service. The system is designed to 
accept and evaluate statements expressed in the 
APL language. A prime objective of the system’s 
designers has been to permit you, as a user, to 
ignore the underlying machinery. You should have 
only to describe in APL the calculation you want. 


Nevertheless, if automatic machinery is to be used 
to evaluate APL expressions, some of your instruc- 
tions must, of necessity, be directed not to the APL 
interpreter but to the system that provides the en- 
vironment in which APL computations take place. 
For example, that’s necessary when you initiate 
contact with the system and are identified as one 
of its enrolled users, or when you terminate a 
work session by “signing off.” There are several 
other points at which you may need to commun- 
icate directly with the system. 


To permit you to address certain commands direct- 
ly to the system that provides the service, there is 


a specialized language of system commands. 
These are not part of the APL language, and are 
not permitted to appear as part of a user-defined 
function. They would be of no use or interest to 
a person using APL strictly as an abstract lan- 
guage without automatic evaluation (for example, 
at a blackboard). But they are necessary to anyone 
using APL at a machine; they are used to com- 
municate certain essential matters of housekeeping 
directly to the system. For this reason, when 
you're using the SHARP APL system, you need 
to become familiar not only with the APL lan- 
guage itself, but also with the system commands. 


Because system commands are essential to certain 
aspects of work with the system, but are used 
differently from the APL language itself, it is im- 
portant to recognize the distinction between them. 
But since both are necessary to carry out calcula- 
tions with the help of the machine, they are treat- 


ed together in the same manual. 
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THE SYNTAX OF APL 


The syntax of a language is the body of rules that 
govern how its various parts can be put together 
to form valid statements. In order to describe the 
syntax, it’s necessary first to identify the major 
classes of things that may appear in a statement 
written in APL. The four classes are: 


Data including constants, variables, and 
results 
Functions including primitive functions and 


defined functions 
Operators (i.e. axis, product, scan, reduce) 
Punctuation including delimiters and separators 
The sections that follow introduce these terms, and 
then use them in describing the syntax of APL. 
Functions and data 


In general, computing is concerned with two kinds 
of things: functions and data. 


In APL, an element of data is either a number 
or a character. For example, below are represented 
three numbers: 


18 44.6 6.02E23 
and three characters: 

Z20 
A data object may be an array containing any 
number of data elements arranged in a rectangular 
structure, or a package, containing any number 
of names and the objects they refer to. 
A function links each member of one set of data 


to some member of another set. This is a one-way 
process: a function is a mapping from one set of 


data to another set. The set of all possible data 
from which the linkage runs is called the func- 
tion’s domain. The set of all data to which the 
linkage leads is called the function’s range. 


Algebra is concerned with the properties of func- 
tions. Computing is concerned more specifically 
with evaluating functions. When you evaluate a 
function, you start with some particular data, and 
compute the specific data to which the function 
links it. The data you start with must belong to 
the function’s domain. The data you start with on 
any particular occasion is called the argument of 
the function. Some functions (for example, multi- 
plication) take two arguments. The set of data to 
which the function links the argument (or argu- 
ments) is called the result. 


Each time you evaluate a function, you replace a 
statement that contains two kinds of things (a 
function and the data that are its argument) with 
a single kind (the data found as the result). To 
evaluate an expression, you take a statement that 
at first contains things other than data, and reduce 
it until you have a result that consists solely of 
data. For example, in the expression 


2x3 


the function “times” (represented by the symbol 
x) takes as its arguments the numbers 2 and 3. 
The function “times” links a pair of numbers to 
a single number, their product. When you evaluate 
2x3, youre replacing the expression 2x3 by its 
result, the number 6. 


Primitive functions, defined functions, and 
programs 


Programming is the art of defining new functions 
that take as their arguments some data you have, 
and produce as their results some data you want. 
A program is usually a definition for a function. 
Presumably, if there already exists a function that 
does just what you want, you won’t need a new 
definition; so, in practice, programming is writing 
a definition for a new function that would not 
otherwise be available to you. 


A definition must be stated in terms that can be 
understood. The primitive functions of a pro- 


gramming language are those functions that need 
no explanation. The primitive functions of 
SHARP APL are those that the SHARP APL 
system always knows how to evaluate; you don’t 
have to tell it how to do so. Every program 
depends on a series of definitions which in the end 
must come down to the primitive functions, the 
things that need no further explanation. Thus, the 
definition of a defined function (that is, a “pro- 
gram”) is written either by referring to other 
defined functions, or else in terms that need no 
explanation. 


Each of the algebraic functions that is primitive 
to APL is represented by a symbol. Each of these 
symbols is a single character, for example 
+ x - +. Wherever possible, the symbols used in 
APL are the same as those already familiar in 
arithmetic or algebra. But there are many func- 
tions for which algebra has no established symbol. 
For those functions, a symbol is coined in APL. 


In addition to the functions represented by a single 
symbol, there is also a set of primitive functions 
known as system functions, each of which is des- 
ignated by the symbol [] followed by certain letters 
(for example, DDZ, OREAD, etc.). 


A defined function (or “program”) is represented 
not by a symbol but by an arbitrary name, com- 
posed of one or more alphanumeric characters. 
(See Chapter 6 for a discussion of the terms 
“functions” and “programs”; see Chapter 7 for a 
description of allowable names. ) Generally speak- 
ing, except for the fact that it is designated by a 
name rather than by a symbol, a defined function 
(once defined) can be used in the same way as 
a primitive function. 


Data—constants, results, and variables 


If numbers or characters are stated directly in an 
APL expression, they are said to be constant. 
That is, their value is given explicitly, rather than 
as the result of evaluating an expression or of 
looking up the meaning of an arbitrary name. In 
an expression such as 


2x1.01 1.07 1.125 
the number 2 and the array of numbers 


1.01 1.07 1.125 are constants. 
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When the expression 2x1.01 1.07 1.125 is 
evaluated, a result is generated. The result is an 
array of data, not stated explicitly in the original 
statement, but produced by it. Such a result may 
be used as the argument of some other function. 
For example, if there exists a defined function 
called INVEST, and that function is to be applied 
to the data resulting from 2x1.01 1.07 1.125, 
that may be indicated by the expression 


INVEST 2x1.01 1.07 1.125 


In that case, the argument of the function 
INVEST is the data that result from evaluating 
2x1.01 1.07 1.125. The values that constitute 
the argument of INVEST are neither named nor 
explicitly written, but are generated as a result of 
evaluating the expression to the right of the name 
INVEST. 


Certain structures or values of data, although they 
can be generated as results (by writing expressions 
which, when evaluated, produce them), cannot be 
written as constants. For example, data arrays 
may have many axes (dimensions), but constants 
(and keyboard entries) are limited to data that can 
be written in a single line; see the discussion of 
data structures and of data entry. 


A collection of data can be given a name. A named 
collection of data is called a variable. As with 
defined functions, the name used for a variable is 
arbitrary, and consists of one or more alphabetic 
characters. Once a name has been assigned to a 
collection of data, each subsequent reference to 
that name is interpreted as reference to the data 
thus named. For example, if the name PRICES has 
been given to a collection of data, then the expres- 
sion 


2xPRICES 


means that a result is to be generated by doubling 
whatever data are referred to by the name 
PRICES. 


The symbol + is used to associate a name with a 
value. The data thus named may have arisen ei- 
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ther as a constant (for example, in an expression 
such as PRICE<240 1605 910.5) or as the re- 
sult of evaluating an expression (for example, 
NEWRATE+1 .15xOLDRATE). 


Functions, derived functions, and operators 


A function (whether primitive or defined) takes 
data as its argument (or arguments) and returns 
data as its result. An operator does something 
analogous but different. It modifies the meaning 
of a function. An argument of an operator may be 
a primitive or derived function rather than data. 
An operator returns as its result not data but a 
function. The function thus produced is called a 
derived function. For example, in the expression 


+/X 


the symbol / signifies the operator called reduc- 
tion. It modifies the function + (which ordinarily 
takes two arguments) to form the function “sum- 
mation” (which takes only one argument, the 
array of data to be summed). 


The syntax of operators is unlike the syntax of 
functions. A function applies to the entire expres- 
sion to the right of it, whereas an operator applies 
to what’s to the left of it (usually a primitive 
function). For example, consider the expression 


Ax+/[1] X*2 


The expression contains two operators: the reduc- 
tion operator /, and the axis operator [ ]. The 
reduction operator / applies to the function + im- 
mediately to the left of it. Together they form the 
derived function “summation.” 


The axis operator, indicated in the example by 
[1], applies to the derived function immediately 
to the left of it, changing it from “summation” to 
“first-axis-summation.” The expression thus 
becomes 


A x FIRST-AXIS-SUMMATION Xx2 


In that expression, A is to be multiplied by the 
result of the first-axis-summation of X*2. 


Notice that the symbols / \ and the brackets 
[ ] are used in two senses: each may indicate 
either a function or an operator. Which sense is 
intended depends on whether the object to the left 
is a primitive function or an expression. When the 
object to the left is a primitive function, the sym- 
bols / \ and [ ] indicate an operator. When the 
object to the left is an expression (or simply a 
variable), the symbol indicates a function. (There 
is also a school of thought whose adherents argue 
that compression and expansion are operators, but 
the point makes little difference to the issues dis- 
cussed here.) 


Operator Function 





/ Reduction Compression 
4 Scan Expansion 
[ ] Axis Indexing 






Operator 

















Primitive operator 
symbol 

Defined (none) 

Derived (none) 


Summary of forms in which operators, functions, and data may appear 


A function may be a primitive (denoted by a symbol or distinguished name), or a defined function 
(denoted by an arbitrary name), or a derived function (produced as the result of an operator). In 
similar fashion, data may appear as a constant, as a variable (denoted by an arbitrary name), or as 
the result of a function. The possible forms are summarized in the following table: 


Function Data 
eee Sa ee 


function constant 
symbol 


named function 
(arbitrary name) 


result of 
evaluating 
an operator 


The product operator, represented by the symbol 
called “dot” . is a dyadic operator. It refers to the 
dyadic primitive functions immediately adjacent to 
it on either side. Its left argument may be omitted, 
but when it is, its place must be held by the 
symbol o (“null” or “jot”). When both arguments 
are present, the product operator forms an inner 
product; when one argument is present (on the 
right), the product operator forms an outer 
product. For example: 


A+.xB The plus-times inner product of A 
and B 


Ac.xB The times outer product of A and 
B 


Operators exist only as primitives, and may be 
used only to modify certain primitive functions. 





























named variable 
(arbitrary name) 






result of 
evaluating 
an expression 
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Punctuation 


The remaining broad syntactic class (in addition 
to data, functions, and operators) is punctuation. 
This category includes delimiters, separators, and 
certain characters used in entering or displaying 
numbers (such as the decimal point ., the high 
negative sign ` used to indicate that a number is 
negative, or the letter F that appears as part of a 
number expressed in exponential form). Delimi- 
ters and separators are described in the sections 
that follow; characters appearing in the represen- 
tation of numbers are discussed in the chapter en- 
titled “Entry and Display of Data Arrays.” 


Delimiters: Delimiters are symbols used to mark 
the beginning and end of a set of characters to be 
treated together. For example, in an expression 
such as (A+B)xA-B, the parentheses indicate that 
A+B is to be treated as a unit in evaluating the 
entire expression. Similarly, brackets [ ] sur- 
round an index (that is, a list of expressions which 
identify particular positions within an array ). 
Note: in British usage, the term “brackets” may 
refer to the symbols ( ); however, in this manual, 
the symbols ( ) are called “parentheses,” while 
the word “brackets” refers exclusively to the 
symbols [ ]. 


A sequence of characters to be treated simply as 
a character constant (and not as an APL expres- 
sion) is delimited by quote marks. Unlike par- 
entheses or brackets, opening and closing quotes 
do not have distinct symbols in APL; the same 
symbol ' is used as the delimiter at each end of 
a character constant. 


Separators: A separator is a single character 
which serves to separate one part of a line or 
expression from another. Separators include the 
blank and the following symbols: 


ca; 


Within a line, a colon separates the label at the 
beginning of the line from the rest of the line; a 
diamond, ©, separates executable statements within 
a line; and the lamp, 9, separates a comment at 
the end of a line from the rest of the line. The 
semicolon ; is used to separate expressions used 
in indexing and formatting, and names in the 
header line of a function definition. The term 
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“line” is discussed in the section headed “Line: the 
Unit of Execution.” 


Blanks: Except as they appear as elements of a 
character array, blanks are not significant in APL. 
However, the characters used to represent a single 
number, and the characters used to form a single 
name, must not be separated by blanks (or by 
anything else). At least one blank (several, if you 
like) is required to separate two adjacent sets of 
characters which otherwise would be read as a 
single name or a single number (for example, to 
distinguish FAT CAT from FATCAT, or X11 from 
X 11, or the single number 2001 from the number 
pair 200 1). Apart from that, blanks are not sig- 
nificant. You may insert extras or leave them out, 
as you like. 


Each blank within a character constant is a char- 
acter, and significant in the same way as any other 
character. 
























List of delimiters 

( ) Parentheses: Parentheses mark the bounda- 
ries of an expression. They are used in 
matching pairs (referred to as “left paren” 
and “right paren”) to mark the beginning 
and end of an expression. Since the right 
argument of any function is always the en- 
tire expression to the right of it, it is never 
necessary (but not harmful) to put paren- 
theses around the right argument of a func- 

tion. 


There are only two situations in which par- 
entheses are required: 


1. Surrounding an expression whose result 
is to be the left argument of a function. 


2. Surrounding the right argument of (FMP 
when it is a list of items separated by semi- 
colons. 


A line whose first non-blank character is a 
right parenthesis, ), is a system command. 
A system command is not part of the APL 
language, and may not be part of a function 
definition. See the section entitled “Distinc- 
tion Between the APL Language and the 
APL System” and the chapter entitled “Sys- 
tem Commands.” 































© 























C ] Brackets: 








Brackets are used solely to en- 
close an expression used as an index (for 
example, A[J+1], the Z+1th members of 
A) or to indicate selection of an axis with 
the axis operator (for example, +/([I+1 JA, 
the sum over the I+1th axis of A). Like 
parentheses, brackets are used in matching 
pairs, referred to as “left bracket” and 
“right bracket.” 








Quotes: The quote mark is used to iden- 
tify character data; that is, to delimit a char- 
acter constant. Within a pair of quotes, the 
quote character itself is denoted by two con- 
secutive quotes. A character constant thus 
runs from the first character preceded by a 
single quote to the next character that is 
followed by a single quote. For example, in 
the expression X«+'CAN''T BE", there is 
one character constant, consisting of the 
eight characters CAN'T BE (including one 
blank character between T and B). 


The system rejects a line containing un- 
balanced quotes with the message 
OPEN QUOTE. Then it gives you a chance 
to correct the line. However, quotes occur- 
ring within a comment are not checked. 
Note that any characters appearing between 
a pair of quote marks are treated solely as 
character data, and have no significance as 
names, functions, operators, or punctuation. 


List of separators 
a ETEA 


Diamond: The diamond is used solely to 
separate statements within a line. A 
diamond acts as a complete separator, so 
that the statements it separates need not be 
otherwise delimited, and do not need to be 
enclosed in parentheses. For that reason, a 
diamond may not be used inside an expres- 
sion. 


Semicolon: The semicolon is used to sepa- 
rate the local names in the header of a func- 
tion definition. It is also used to separate 
expressions within a list. A list is a collec- 
tion of several expressions, each of which, 
when evaluated, produces a data array. A 


list does not form a single data object, and 
may not be assigned to a variable. Lists are 
used: 


1. To list the expressions used to index the 
successive axes of a multi-axis array. 


2. To list the expressions to be formatted 
by the formatting primitive FMT. 





The semicolon is a complete separator of 
expressions, and so the expressions thus 
separated do not need to be enclosed in par- 
entheses. 


Colon: The sole use of the colon is to 
separate a line label from the line of a pro- 
gram (or of keyboard input) that it labels. 
The name to the left of the colon is a name 
for the line of input, but is not executed. 
Everything to the right of the colon is the 
line to be executed. A line can have at most 
one colon (except as colons may occur with- 
in a character constant or comment). A line 
may not begin with a colon. 


Lamp: The lamp symbol indicates a com- 
ment. A comment is text which is used to 
illuminate the programmer’s purposes, but 
which is not itself part of a statement to be 
executed. Within a line of a program (or 
a line of keyboard input), everything to the 
right of the first lamp symbol (reading from 
left to right, and not counting one located 
within a character constant) is comment, 
and is not executed. 


Blank: Within a numeric constant, a 
blank is used to separate the digits of one 
number from those of the next. For exam- 
ple, 7 .6 is the pair of numbers 7 and 
-6, whereas 7.6 is a single number. With- 
in a statement, one or more blanks must be 
used to separate one name from another 
name or from a number occurring next to 
it. The blank thus serves to prevent a pair 
of adjacent names from being treated as one 
long name. Additional blanks are ignored. 
It is never necessary to put blanks around 
the symbol used to denote a primitive func- 
tion. 
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Line: the unit of execution 


The APL system executes APL line by line. A line 
is thus the minimum unit of work you can request 
the system to do. That is true whether the line is 
one that you enter from the keyboard, or a line 
that is part of the definition of a defined function. 


When you work from the keyboard in what is 
called “immediate execution mode,” what you type 
until you press the RETURN key constitutes a 
line of entry. Your line may include any number 
of statements, and these in turn may include 
references to any number of defined functions, as 
well as primitive functions, operators, variables or 
constants. (This is a point on which SHARP APL 
differs from some other implementations of APL. 
In those systems, a line consists of at most one 
statement, and so the terms “line” and “statement” 
are there treated as synonyms. ) 


The definition of a function consists of a single 
line (called the function’s “header”) which des- 
cribes the function’s syntax and its use of names, 
followed by a sequence of executable lines known 
as the “body” of the definition. When you are 
entering the definition of a defined function, the 
lines you enter from the keyboard are not im- 
mediately executed, but are collected by the system 
and stored. Later, when you make use of the func- 
tion thus defined, the system executes the lines of 
its definition, one after another in sequence. 


Thus, for the APL system, the line is the basic 
unit of work; the system starts to execute a line 
entered from the keyboard only when the line is 
complete. 


When a line is entered from the keyboard for 
immediate execution, execution starts as soon as 
that line is entered. To “enter” a line is to in- 
dicate that it is complete. This is done by pressing 
the RETURN key. Pressing RETURN signals 
that the line is complete; however, the “return” 
character does not itself become part of the line. 
(The return character may be an element of a 
character array, but it cannot be entered directly 
from the keyboard; see the discussion of enterable 
and displayable characters. ) 


The record of a work session appears at the ter- 
minal as a dialogue between you (the user) and 
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the computer. After each line is entered from the 
keyboard, the system executes it and displays its 
result (if that’s appropriate, and if there is one). 
Then you enter another line to be executed, and 
its result is displayed, and so on, in a succession 
of alternations. 


Divisions of a line: label, body, comment 


A line consists of three parts: the label (a name 
for the line), the body of the line (containing the 
statements to be executed), and a comment. 


The label (if present) is separated from the body 
by a colon. The colon serves both to separate the 
label from the body, and to identify the name to 
the left of it as a label. A line doesn’t have to have 
a label; a line within a definition often needs no 
label. It’s probably pointless (but nevertheless per- 
missible) to label a line entered from the keyboard 
for immediate execution. A line may have at most 
one label. A labelled line may have a body that 
is empty; in that case, it still requires the colon. 


The value and use of line labels is discussed in the 
section entitled “The Internal Environment of a 
Function,” and the chapter entitled “Branch State- 
ments.” 


Statements within the body of a line 


The body of a line consists of one or more state- 
ments, separated from each other by the statement 
separator ©. A statement may be empty. 


The diamond © acts as a complete separator; 
that is, the statements thus separated do not have 
to be delimited in any other way; in particular, 
they need not be enclosed in parentheses. 


Within the body of a line, the various statements 
are executed in sequence from left to right. 


A comment is some explanatory text attached to 
a line to help you understand why it’s there or 
what it does, but which is not to be executed. A 
comment is indicated by the symbol a (“lamp’”—a 
comment is supposed to illuminate the program for 
you). Anything to the right of the first lamp 
symbol that isn’t inside a quotation, is comment. 
The system ignores it. 


A line need not have a comment (in which case 
it doesn’t need a lamp symbol). A comment can 
also occupy an entire line (in which case the lamp 
symbol a will be the first character on the line). 


Types of statements 
APL statements are of two types: 


1. Evaluation: An evaluation statement is an 
expression, involving any number of primitive 
functions, defined functions, variables, or con- 
Stants, subject to the syntactic rules of the lan- 
guage. The system evaluates a statement by substi- 
tuting for each operator-and-its-argument (or ar- 
guments) the appropriate function, and for each 
function-and-its-argument (or arguments) the ap- 
Propriate value. It does that until all functions 
have been evaluated. Then the expression has been 
entirely reduced to a single data object, or, in the 
case of a function that doesn’t return a value, en- 
tirely eliminated. An expression may include as- 
signment, thereby causing the value of all or part 
of the expression to be associated with a name. 


When the expression has been completely exe- 
cuted, it may have a result; if it has, the system 
may display it (see “When the Result is Dis- 
played”). 


2. Branch: A branch statement is distinguished 
by having as its first non-blank character, the 
branch arrow +. The arrow may stand alone, or 
may be followed by an expression. If it’s followed 
by an expression, the system evaluates the expres- 
sion and uses the result to determine the number 
of the line to be executed next. A branch statement 
does not have a result. 


Expressions 


An expression consists of a function and its argu- 
ments. A function may be a primitive function 
(denoted by a symbol or distinguished name), a 
defined function (denoted by a name), or a de- 
rived function (produced by an operator acting on 
a primitive function). 


Within an expression, the argument of a function 
may itself be an expression. Expressions may be 
nested within expressions to any level. 


Some functions take no argument, while others 
require one or two arguments. 


If a function takes one argument, the argument 
appears to the right of the function. For example, 
when the function - (negation) is applied to data 
called X, that is written 


-X 


Similarly, when a defined function called F is ap- 
plied to data called X, that is written 


FX 


If a function takes two arguments, they appear one 
to the left and one to the right of the function. For 
example, when the function x (multiplication) is 
applied to data called A and B, that is written 


AxB 


and similarly, if a defined function called F is 
applied to data called A and B, that is written 


AFB 


An expression may be enclosed in a pair of par- 
entheses. Where the left argument of a function 
is itself an expression, it must be enclosed in par- 
entheses (but parentheses aren’t necessary for a 
right argument). An expression in which an argu- 
ment is itself an expression is called a compound 
expression. For example, 


(A+B) x A-B 


is a compound expression. The function x takes 
as its left argument the result of evaluating A+B 
and as its right argument the result of evaluating 
A-B. Within any expression, the first function 
(reading from left to right) which is not enclosed 
in parentheses is called the principal function or 
the root function of the expression. It’s called the 
root because if you construct a tree diagram to 
represent the expression, it’s the function at the 
root of the tree. 
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result 


AxB (A+B)*(A-B) 


A function accepts values as input and returns a 
value as its result. You can visualize a function 
as a hopper with one or two openings through 
which it receives its arguments, and a single open- 
ing through which it delivers the value of its re- 
sult. An expression can be modelled as the flow 
of data through a series of such hoppers. 






Tree diagram of (A+B) x A-B 
A / \ / 
+ - 


In a diagram such as this, at each node of the tree 
there is a function, while at each leaf there is a 
data object. If the expression contains operators, 
what’s at the node is the derived function that the 
operator produces. 


Evaluating an expression requires a process that 


starts from the leaves, and successively replaces 
each cluster consisting of a node and its leaves 
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result 


Ax+/(41] X*2 










Tree diagram of Ax+/[1] X*2 








derived function 


A +/[1] 


N 


x 


(that is, a function and its arguments) with the 
resulting data. The process continues until there 
are no nodes (functions) left, and nothing but data 
remains. 


If the root function of an expression returns a 
result, then the set of data produced by evaluating 
the expression is the result of the expression. 
However, certain functions do not return a result, 
and so evaluating an expression containing such 
a function produces no result. An expression that 
has no result cannot be the argument of a function. 


An expression may also consist simply of a con- 
stant or a variable, standing alone. For example, 
if there exists a collection of data named X, then 


X 


is a legitimate expression. Similarly, a constant, 
standing alone, is a possible (if uninteresting ) 
expression. For example, if you simply enter a 
constant such as the following 3-element vector: 


18 “44.6 6.02823 


the system responds by displaying its value—the 
same numbers you just entered. That’s because the 
result of such a minimal expression is the data 
named, or the constant. 


When the result is displayed 


If a statement has a result, the system automatical- 
ly displays it unless the statement has a root func- 
tion and the root function is < (assignment). 


The root function of a statement is the first func- 
tion (reading from left to right) that is not en- 
closed within parentheses. 


For a statement whose root function is e (exe- 
cute), the foregoing two rules are applied to the 
rightmost statement within the argument of ¢. 


The practical effect of these rules is that if you 
write a statement that calculates a result and as- 
signs the result to a variable, the system carries 
out the calculation and stores the result (but 
doesn’t display it). If you write a statement which 
calculates a result but you don’t say what is to be 
done with the result, the system displays the result. 
Thus 


X++/DATA*2 


causes the system to calculate the sum of the 
squares of the array DATA and store it under the 
name X. By contrast, the statement 


+/DATA*2 


causes the same calculation, but because the root 
function is not <, the result is displayed. 


If (as in the foregoing example) your statement 
doesn’t include instructions about how to format 
the display, the system applies its own default 
rules of formatting. These rules are described in 
the section headed “System-default Displays.” 


The valence of a function 


The valence of a function is the number of argu- 
ments it takes. A function may have no arguments, 
one argument, or two arguments. The following 
terms are used to describe a function according to 
the number of its arguments: 


0 arguments Niladic function 


1 argument Monadic function 


2 arguments Dyadic function 

A niladic function is identical in appearance and 
use to a variable, with the sole exception that it 
can’t appear to the left of a specification arrow. 
SHARP APL includes a number of niladic primi- 
tive functions (DAZ, DTS, ONAME'S, DNUMS, DAV, 
DUL, OWA, and DZC). A niladic system function is 
used to report the value of some aspect of the 
workspace, or some aspect of the system that is not 
directly subject to your control (that is, one that 
you can’t respecify). 


All other primitive functions are either monadic or 
dyadic. 


Dual use of function symbols 


For many primitive functions, the same symbol is 
used to refer both to a monadic function and to 
a dyadic function. For example, if A and B are 
variables, the expression 


A-B 


refers to the dyadic function “subtraction,” where- 
as the expression 


-B 


refers to the monadic function “negation.” These 
are different functions. The context indicates 
which function is intended. 


When a function appears with an expression im- 
mediately to the left of it, the function is a dyadic 
function. When, within an expression, a function 
appears with nothing to the left of it, or with 
another function to the left of it, it must not be 
a dyadic function. 
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Placement of a function’s arguments 


The definition of a defined function stipulates 
(among other things) whether it is niladic, mon- 
adic, or dyadic. A niladic defined function (like a 
niladic primitive function) cannot appear with an 
argument. A monadic defined function must ap- 
pear with an argument, and that argument must 
appear to the right of the function. 


If a defined function’s definition says it’s dyadic, 
whenever you use that function, you must use it 
with a right argument. However, you may use it 
either with or without a left argument. That is, 
you can use a dyadic defined function either in a 
dyadic sense or in a monadic sense. Which sense 
applies in a given case is determined solely by the 
context. For example, suppose F is the name of a 
dyadic defined function, and B is the name of a 
variable. Then when A is a variable, 


AFB 


is an example of a dyadic use of F, whereas when 
A is a function, 


AFB 


is an example of a monadic use of F. 


When you write the definition of a function that 
may be used either dyadically or monadically, you 
should include a test to decide whether it has been 
used without a left argument, and have the func- 
tion proceed accordingly. 


Within an expression, for any function that takes 
an argument (be it monadic or dyadic), its right 
argument is the expression tothe right of the func- 
tion. The right argument need not be enclosed in 
parentheses, or set off from the function in any 
way, except that if the function has a name and 
its argument begins with a name, the two names 
must be separated by a blank. (Otherwise, they’d 
form a single long name.) 


Within an expression, the left argument of a 
dyadic function is the expression immediately to 
the left of the function. If the left argument is itself 
an expression, it must be enclosed in parentheses. 
However, indexing uses a pair of symbols [ ] for 
a single function, and thus makes unambiguous 
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the boundaries of its argument. For that reason, 
in the expression 


ALI]+B 


ALI] doesn’t need to be enclosed in parentheses. 


Order of execution of statements within a line 


An APL line consists of one or more statements, 
separated by diamonds. Within an APL line, 
statements are evaluated in order from left to 
right. 


Any of those statements may be a branch state- 
ment—that is, a statement in which > is the 
first non-blank character. A branch statement has 
the power to alter which line of a defined function 
is executed next. It may also end execution of the 
statements within a single line before the system 
has reached the statements further to the right. 


Whether a branch statement has any effect de- 
pends on what’s to the right of it. If there is an 
expression to the right of the arrow, but its value 
is an empty array, no branch takes place. Execu- 
tion proceeds with the next statement within the 
line being executed, and (when that’s done) with 
the next line of the defined function. 


But if the expression to the right of > is not 
empty, the system goes immediately to the line 
whose number is the first element in that expres- 
sion, without executing any statements that may 
exist further to the right. 


Order of execution of functions and operators 
within a statement 


APL has only one rule of precedence: operators 
are executed before functions. 


Valence of operators 


The valence of an operator is the number of argu- 
ments it takes. Each operator is either exclusively 
monadic or exclusively dyadic. (This isn’t true of 
functions; you can use most function symbols in 
either a monadic or a dyadic sense.) 


A dyadic operator takes as its arguments the ob- 
jects immediately adjacent to it on each side. 


At present, APL contains two dyadic operators: 
the product operator, denoted by the symbol ., and 
the axis operator, denoted by the symbol [ fol- 
lowed by a matched closing bracket ]. 


The dot that denotes the product operator must be 
used so that it has on each side of it a symbol 
denoting a dyadic scalar primitive function. It can 
also accept as its left argument the symbol 
(“null”). 


The axis operator takes as its left argument a 
primitive function or a derived function (produced 
by another operator), and as its right argument 
an array. 


A monadic operator takes as its argument the 
primitive function immediately to its left. 


There are at present two monadic operators: scan 
(denoted by \), and reduce (denoted by /). 


Identifying the operators within a statement 
The following symbols may denote operators: 
LoS ca Ga 


But each of those symbols may be put to some 
other use. You can tell when any of them denotes 
an operator by the following rule: 


When a symbol that could denote an operator has 
a primitive function or operator to the left of it, 
it does denote an operator. 


Order of execution of operators 


It’s possible for two operators to occur side by side 
in an expression, or separated from each other 
only by a function or array that is an argument 
of one of them. (In principle, such a sequence 
might contain even more than two operators, but 
at present the number of operators is severely 
limited, and so at present there aren’t any valid 
instances of more than two consecutive operators. ) 


When a statement contains several distinct Opera- 
tor sequences (separated from each other by func- 
tions that are not the arguments of any operator) 
it is immaterial which sequence is evaluated first. 
In practice, the system evaluates the various 
sequences from right to left. 


Within an operator sequence, the operator at the 
right takes as its left argument the entire balance 
of the operator sequence to its left. For example, 
the statement 


At/[1] X*2 
contains the operator sequence 
+/[1] 


The axis operator [1] takes as its argument the 
entire balance of the operator sequence to its left, 
that is +/. 


Since a tree structure must be evaluated from the 
leaves towards the root, saying that an operator 
takes as its argument the entire balance of the 
operator sequence to its left boils down to saying 
that the system has to evaluate the operator on the 
left before it can evaluate the others. Hence, in 
practice, when the system evaluates a sequence 
such as +/[1], the first thing it does is evaluate 
the reduction operator /, for its argument +. That 
yields the derived function “summation.” 


Then the system evaluates the next operator to the 
right, which, in the example, is the axis operator. 
The right argument of the axis Operator is the 
number 1 and the left argument is the derived 
function “summation.” 


The result for the entire sequence is the derived 
function “summation along the first axis.” 


Order of execution of functions within a state- 
ment 


There is no hierarchy of functions; all functions 
(including all primitive functions and any defined 
functions) have equal precedence. That means 
that the order in which functions are executed 
depends solely on where they are in the statement, 
and not at all on what they are. 
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There are two ways to think of the effect of this 
rule: from the point of view of the person reading 
or writing an APL expression, or from the point 
of view of the system executing it. 


Consider it first from a reader’s point of view. 
APL reads from left to right. Each function takes 
as its argument all of the expression to the right 
of it. (This is the usual convention in algebra for 
functions given arbitrary names.) For example, 
suppose there exist monadic functions with the 
names DISPLAY, ADJUSTED, and PROJECTED. 
Then, in an expression such as 


DISPLAY ADJUSTED PROJECTED DATA 


the function DISPLAY takes as its argument the 
result of evaluating ADJUSTED PROJECTED 
DATA; the function ADJUSTED takes as its argu- 
ment the result of PROJECTED DATA; and the 
function PROJECTED takes as its argument DATA. 


Disregarding any redundant parentheses that 
might enclose an entire expression, the root func- 
tion of an expression is the first function (reading 
from left to right) that isn’t enclosed in parenthe- 
ses. That function takes as its left argument every- 
thing to the left of it, and as its right argument 
everything to the right of it. 


From the point of view of the system (or a per- 
son) evaluating an expression, evaluation must 
start at the leaves of a tree and work back towards 
the root. You can’t evaluate the root function until 
you know the values of its arguments. For that 
reason, the system (more precisely, the interpre- 
ter) evaluates the various functions within a state- 
ment from right to left. 


Starting from the statement’s right-hand end, the 
interpreter scans leftward until it finds a function. 
If the function is modified by an operator, it 
evaluates the operator at once (so that what it has 
now is the derived function that the operator 
produces ). 


If the function takes one argument or no argu- 
ments, the interpreter evaluates the function. 
Similarly, if the function takes two arguments, and 
the left argument is immediately available 
(because it’s a variable or a constant), the inter- 
preter evaluates it. 
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However, if the function takes two arguments and 
the left argument turns out to be an expression 
(evident because the next character leftward is the 
expression’s closing parenthesis), the interpreter 
sets aside the function and right argument that it’s 
been working on, and sets to work evaluating the 
expression to the left. The expression to the left 
runs from the closing parenthesis just found, all 
the way leftward to the opening parenthesis that 
matches it (possibly including other expressions 
nested within it). The interpreter evaluates that 
expression by applying to it the same rule just 
described. Perhaps that expression itself contains 
another expression, so the process will have to be 
repeated. 


When the value of the left-argument expression 
has been found, the interpreter returns to the func- 
tion and right argument that it previously set 
aside, and evaluates the function. 


This sequence continues until the interpreter 
reaches the left end of the statement. Then it 
decides whether the statement it has been dealing 
with is a branch. If > is the leftmost non-blank 
character, the system acts upon the statement as 
a branch. That is, it gives a new value to the first 
element of DZC, which determines which line is to 
be executed next. 


If the statement is not a branch, the system must 
decide whether to display the result. If there isn’t 
any result, of course, no display is needed. See the 
section “When the Result is Displayed,” earlier 
in this chapter. 


Universal application of order of execution 


The order in which functions are evaluated is the 
same for all functions. While this rule is simple 
and consistent, it also differs in some respects from 
conventional treatment of a few functions which 
are traditionally irregular. (As with natural lan- 
guages, it is the simplest and most widely used 
functions that are most likely to have irregular 
forms.) If you’re new to APL, watch out for the 
following consequences of the fact that APL 
syntax is regular in places where traditional alge- 
bra permits exceptions. 


Watch out: Because there is no hierarchy of 
functions, there is no rule in APL that exponentia- 
tion should be executed before multiplication, or 
multiplication before addition. Hence, in APL, the 
expression AxB+C is equivalent to Ax(B+C) but 
not to (AxB)+C. 


Indeed, because a function always applies to what 
is to the right of it, it is never necessary to write 
parentheses surrounding a right argument, and 
hence no APL statement need end in a parenthe- 
sis. There’s one exception: when the right argu- 
ment of [FMT is a list, the list must be enclosed 
in parentheses; see the section “A Note about 
Semicolons and Lists” in Chapter 8 and the des- 
cription of OFMT in Chapter 22. 


In conventional algebra, the equal sign = is used 
(among other things) to denote the equality of two 
expressions; it is understood as a complete separa- 
tor, as though each of the expressions were en- 
closed in parentheses. By contrast, in APL the 
equal sign = is used to denote a proposition (that 
is, a function whose result is Boolean), which may 
be true or false. Thus, in APL = denotes a func- 
tion, and follows the same rules as all other func- 
tions. In particular, A+B=C is equivalent to 
A+(B=C) but not to (4+B)=C. 


In conventional algebra, juxtaposition of the names 
of two variables is often used to indicate multi- 
plication. For example, xy means “the product of 
x and y.” However, in APL, every function must 
be explicitly written. Thus, the conventional forms 
xy or x(y+1) appear in APL as X¥xY and as 
XxY+1 respectively. 


It’s never valid to write two data-objects side by 
side without indicating a function that relates 
them. 


Order in which the arguments of a dyadic 
function are evaluated 


The right argument of a dyadic function is 
evaluated before the left argument. 


It isn’t often that this rule makes any difference; 
after all, the system has to know the value of both 
arguments before it can evaluate the function. But 
there do arise certain cases in which the value of 


part of the expression can vary from moment to 
moment, so that which part the system evaluates 
first might make a difference. For instance, that 
might happen if, in order to evaluate an argument, 
the system had to make reference to a shared vari- 
able or to a shared file, whose value might be set 
independently by someone else. 


Order of execution also matters if you construct 
an expression in which the same variable appears 
in both the left argument and the right argument, 
and is at the same time re-set. It is difficult to 
think of good reasons to engage in this sort of 
tricky coding (other than to discover what the 
system does with such pathological cases). But you 
might concoct an example such as the following, 
and wonder what the value if X should be: 


A+3 
X+(A5)xA 


That sort of coding may be confusing to read, and 
should probably be avoided for that reason. It 
makes it difficult to take a program written in 
such a manner from one system to another, 
because this is an issue on which implementations 
vary. Moreover, the SHARP APL system’s treat- 
ment of such cases has not yet been made entirely 
consistent with the rules. While that inconsistency 
remains, you should avoid such expressions al- 


together. 
$ 
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Chapter 5: 


CLASSIFICATION 
OF APL PRIMITIVE 
FUNCTIONS AND 
OPERATORS 





Classification of functions 


The valence of a function is the number of argu- 
ments it takes. A primitive function may have 


0 arguments Niladic function 
1 argument Monadic function 
2 arguments Dyadic function 


A function’s valence indicates how many argu- 
ments must appear in a statement that makes use 
of it. A “niladic function” might seem to be a 
contradiction in terms. When you write a state- 
ment containing a niladic function, you write it 
without an argument. Similarly, a monadic func- 
tion is a function that must be written with one 
argument, and a dyadic function is one that is 
written with two arguments. Since many function 
symbols may be used either monadically or 
dyadically, valence is sometimes determined from 
context. 


Each primitive function of APL is represented by 
a single symbol, or, in the case of system functions, 
by the symbol [] followed by certain letters. 


The concept of “conformability” 


When a function takes two arguments, there may 
be a requirement that the shape of one argument 
in some manner conform to the shape of the other. 
The arguments may have to have the same rank, 
or the same shape, or to differ in rank or shape 
in a particular way. 


Two arrays whose rank and shape are acceptable 
for a particular dyadic function are said to be 
conformable. The conformability requirements of 
a function are described with the definition of 
each. A common set of conformability rules applies 
to a broad class of functions called “scalar func- 
tions.” 
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The concept of “scalar function” 


A scalar function is one that is defined on a scalar 
argument (or arguments) and, given scalar argu- 
ments, returns a scalar result. All the familiar 
functions of arithmetic are scalar functions. 


The scalar functions constitute an important class. 
Their members follow a common set of rules 
regarding the shape and structure of their argu- 
ments. Applied to array data, a scalar function 
returns a result that has the same shape as the 
argument(s). 


Those scalar functions that are dyadic can be com- 
bined with the product operator to form inner and 
outer products and with the scan and reduction 
operators. 


Scalar functions that are monadic 


A monadic scalar function can be applied to an 
array argument of any rank and any shape. It 
returns as its result an array having the same rank 
and shape as its argument. Each element of the 
result consists of the result found when the func- 
tion is applied to the corresponding element of the 
argument. A scalar function thus distributes over 
catenation, since for any monadic scalar function 


£X,Y + (£ X),( ¥) 


The following are monadic scalar functions. They 
are shown as they would appear with an array 
argument named Y: 


+Y Conjugate of Y 

xY Signum of Y 

-Y Algebraic negation of Y 

+Y Reciprocal of Y 

*Y Exponential of Y (i.e. e to the power Y) 
@Y Natural logarithm of Y 

|Y Magnitude (i.e. absolute value) of Y 

‘Y Factorial Y or Gamma function of Y+1 
oY Pi times Y 

LY Floor of Y 

[Y Ceiling of Y 

~Y Logical negation of Y 

?Y Roll of Y (i.e. a random integer from 1Y) 


Whether ?Y is a scalar function is debatable. The 
result contains an element directly corresponding 
to each element of the argument, but (since the 
values are random} the usual identities are not 
satisfied. 


Scalar functions that are dyadic 


The following are dyadic scalar functions. They 
are shown as they would appear applied to a left 
argument array X and a right argument array Y. 


X+Y X plus Y 

X-Y X minus Y 

XxY X times Y 

X+Y X divided by Y 

X*xY X to the power Y 

X@Y Base-X logarithm of Y 

X|Y X residue of Y 

X!Y Binomial: Y things X at a time; related to 
the Beta function 

XLY Minimum of X and Y 

X[Y Maximum of X and Y 

XAY Logical X and Y 

XvY Logical X or Y 

XAY Logical X nand Y 

XwY Logical X nor Y 

X<Y Proposition: X is less than Y 

X<Y Proposition: X is not greater than Y 

X=Y Proposition: X equals Y 

X#Y Proposition: X not equal to Y 

X2Y Proposition: X is not less than Y 

X>Y Proposition: X is greater than Y 

XoY Circular function X on Y 


Non-scalar primitive functions 


No single rule unites those functions that are not 
scalar functions. They are listed here, and des- 
cribed individually in the chapter entitled “Non- 
scalar Primitive Functions (Other than System 
Functions).” 


oY Shape of Y 

XpY Reshape of Y to have shape X 
oy Reverse of Y 

XOY Y rotated by X 
XY Transpose of Y 

XXY The X transpose of Y 
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zY. Ravel of Y 
X,Y X catenated (or laminated) to Y 
XtY X take Y 
XY X drop Y 

ty The first Y integers 
X.Y The index of Y in X 
XLY] The Yth elements of X 
X/Y X compressing Y 
X\Y X expanding Y 

yY Downgrade of Y 

AY Upgrade of Y 





XeY Proposition: X is a member of Y 
XTY The X representation of Y 
XLY The X base value of Y 

EY A generalized matrix inverse of Y 














aY X matrix-divide Y 
X<Y The variable X is assigned the value Y 


ay Execute the line Y 
pY The character representation of Y 
X¥Y The X character representation of Y 


X?Y Deal of X from Y 


Branch 


A statement whose first significant character is the 
symbol > is a branch. This is not a function (it 
has no result) but serves to select which line is to 
be executed next. 


>Y Branch to Y 


Operators 


There are four operators. Each modifies the action 
of a function, or of a pair of functions, to produce 
a new function. The new function cannot be given 
a name. It is referred to as a derived function. In 
the list that follows, X, Y and I indicate data ar- 
rays, and f and g indicate primitive scalar func- 
tions. 


Xf[I] Y Axis operator: selects axis along 
which f is effective 


f/Y Reduction operator: the f reduction of 
Y 
fY Scan operator: the f scan of Y 


Product operator: produces two classes of derived 
functions. 


Xo .gY The g outer product of X and Y 


Xf.gY The f g inner product of X and Y 


System variables and functions 


Strictly speaking, system functions aren’t part of 
the APL language. Nevertheless, they are primi- 
tives recognized by the SHARP APL system. In 
that regard, they’re like system commands, which 
are also outside the APL language but recognized 
by the SHARP APL system. For that reason, 
system variables, system functions, and system 
commands are all described in this manual. 


A system command can only be entered manually 
from the keyboard, while the system is in im- 
mediate execution mode. Its first significant char- 
acter is always ) (right parenthesis). System 
commands are described in a separate chapter. 
Unlike system commands, system variables and 
system functions may be used either from the key- 
board or within a defined function. The name of 
each consists of the symbol O followed by one or 
more letters. A name beginning with [ is called 
a distinguished name. The symbol [ can’t appear 
in any name that you create (for example, as the 
name of a defined function), and you can’t create 
new distinguished names. 


A system variable is a variable to which you can 
assign a value in the usual way, but which has a 
special significance to the APL interpreter. Its 
value influences the way work is done in the active 
workspace. Each system variable has a default 
value in a clear workspace, so you need specify its 
value only if you want it to be something different. 


A system function is a primitive function in the 
sense that the system always knows its definition, 
and you need not (and cannot) provide it a defini- 
tion yourself. It is outside the scope of the abstract 
APL language, and hence is not represented by a 
symbol of its own. Rather, it has a name in the 
same manner that defined functions have names, 
but a name that is distinct from any of the names 
that you can use for variables or defined functions. 
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In this way, system variables and system functions 
constitute a set of extensions to the APL language. 
They can appear in programs in the same way as 
primitives can. The functions they provide are of 
great practical significance, and are likely to turn 
up often in production programs. On the other 
hand, they are outside the central corpus of the 
APL language, and hence tend to differ considera- 
bly in the various implementations of APL. If you 


name refers to a system variable, that fact is in- 
dicated by +X appearing to the right of the vari- 
able’s name, to show that you can respecify its 
value. Where a distinguished name refers to a 
function, and the function requires an explicit ar- 
gument, that fact is illustrated with an argument 
Y, or with arguments X and Y. Since certain system 
functions return no result, a function that does 
return a result is shown assigning that result to 


transfer a program between SHARP APL and a variable R. 
some other APL system, you’re likely to find ex- 
cellent agreement on the definition of APL primi- 
tives, but much less consistency in the distin- 
guished names that the various systems recognize, 
or the meanings they attach to them. You might that category is discussed further; a key to these 


think of distinguished names as a way of repre- terms appears following the list of distinguished 
senting useful auxiliary capabilities of the APL names. 
system. 


The word appearing to the right of the sample of 
each distinguished name is an arbitrary classifica- 
tion, indicating the chapter of the manual in which 


The following is a list of distinguished names in 
the SHARP APL system. Where a distinguished 






DISTINGUISHED NAMES IN SHARP APL 











Name Classification 
creme eee 


Description 
ee ee 














































OAT Info Account information 
X DAPPEND Y File Append X to file Y 
RX [JAPPENDR Y File Append X to file Y and return component number 
Re [JARBIN Y I/O Arbitrary input from terminal 
DARBOUT Y I/O Arbitrary output to terminal 
Re AV I/O Atomic vector (all possible characters) 
Re DAVAIL 10 File File system availability 
R- (BOUNCE Y Task Terminate (i.e. “bounce” ) task Y 
Re DCR Y Def Canonical representation of function Y 
X DCREATE Y File Create file X share-tied to Y 
OCT «Xx WS envt Comparison tolerance 
Re DDL Y WS envt Delay Y seconds 
DODROP Y File Drop components from start or end of file Y 
DER Trap Report of last trappable event 
X DERASE Y File Erase file with name X and tie-number Y 
Re [DEX Y Def Expunge objects Y 
R-X DFD Y Def Represent, fix, or erase definition Y 
OFF File File primitive (substitute for FF) 
UFHOLD Y File Hold file Y with permission 
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Re 

Re 

Re 
X 








X 







Re 
Re 
Re 









Name 


DFI Y 


OFX Y 
ODHOLD Y 














ai 
= 
5 
het 








OPNAMES Y 
DPNC Y 
OPNC Y 
OPP -X 
OPPDEF Y 
OPPDEF Y 
OPSEL Y 
OPVAL Y 
OPW <X 
OQLOAD Y 
ORDAC Y 
ORDCI Y 
OREAD Y 
ORENAME Y 





X DREPLACE Y 


ORESIZE Y 
ORL +x 
DRUN Y 
ORUNS 
OSC 





DFMT (A;B;.. 


DISTINGUISHED NAMES IN SHARP APL (continued) 


Classification 





xiZ) 


Data 
Data 
Def 
File 
Session 
WS envt 
Info 
File 
Load 
WS envt 
File 

WS envt 
WS envt 
File 
1/O 


WS envt 


Shvars 


Description 





Numeric vector from character string 
Formatted character matrix representing A B Z 
Fix function from representation Y 

Hold file Y 

Horizontal tabs 

Index origin 

Line counter 

Names of files in library Y 

Load workspace Y 

Latent expression 

Names of files currently tied 

Returns nameclass of names Y 

Returns matrix of names in class(es) Y 
Tie-numbers of files currently tied 

Terminal output control 

Form package from names Y 

Form package with name X and value Y 
Define all objects in package Y 

Define objects X from package Y 

Form package lacking objects X of package Y 
Into package X insert package Y 

Lock functions in package Y 

Lock functions X in package Y 

Names of objects in package Y 

Nameclass of objects in package Y 

Nameclass of objects X in package Y 

Print precision 

Define (with protection) names from package Y 
Define (with protection) names X from package Y 
Form package of names X from package Y 
Value of variable X from package Y 

Print width 

Quiet-load workspace Y 

Read access matrix of file Y 

Read component information from file Y 

Read file component Y 

Rename as X the file tied to Y 

Replace file component Y by value X 

Resize to X the file tied to Y 

Random link 

Run N-task with parameters Y 

Report active tasks 

Returns 1 following shared-variable state change 
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DISTINGUISHED NAMES IN SHARP APL (continued) 





Name Classification Description 
=o eee ees 




















































OSIGNAL Trap Signal error Y 
X (SIGNAL Y Trap Signal error Y with message X 
R- (SIZE Y File Report size of file Y 
OSP +X Session Session parameter 
X DSTAC Y File Set access matrix of file Y to X 
X DSTIE Y File Share-tie file X to number Y 
Re svc Y Shvars Report access control of variables named in Y 
ReX SVC Y Shvars Set access control of variables named in Y to X 
Re QSVN Y Shvars Set workspace clone ID to Y 
Re QSVo Y Shvars Report level of coupling of variables named in Y 
ReX QSVO Y Shvars Offer to share variables named in Y with processor 
identified in X 
Re (SVQ Y Shvars Report share offers from Y 
Re (SVR Y Shvars Retract offer to share variables named in Y 
Re SVS Y Shvars Report state of variables named in Y 
X DTIE Y File Exclusive-tie file X to Y 
DTRAP <X Trap Set events to be trapped and actions to be taken 
ke DTS Info System timestamp 
Re DUL. Info System user load 
DUNTIE Y File Untie file(s) Y 
Re WI Y Data Validate as numeric fields of Y 
R- [WA Info Work area remaining 
R-X [WS Y Info Workspace information 







Key to classifications of distinguished names Pkg See “System Functions for Man- 
ipulating Packages” 
Data See “System Functions for Represent- 
ing and Converting Data” Session See “Session Variables” 
Def See “System Functions for Function Shvars See “System Variable and Functions 
Definition” for Sharing Variables” 
File See “System Functions for Managing Trap See “System Function and Variables 
Files” for Event Trapping” 
Info See “System Functions for Reporting Task See “System Functions for Batch 
System or Workspace Information” Tasks” 
I/O See “System Functions for Terminal WS envt See “System Function and Variables 
Input/Output” Affecting the Workspace Environ- 
ment” 
Load See “System Functions for Loading a dey 
Workspace” 
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Chapter 6: 


USER-DEFINED 
FUNCTIONS 





USER-DEFINED FUNCTIONS 


Functions and programs 


The APL community tends to use the terms 
“function” and “program” interchangeably. 
Nevertheless, they do have different connotations. 
While these words are not technical terms and are 
not formally defined in SHARP APL, they repre- 
sent the contrasting ends of a range of styles in 
which defined functions can be written, and all of 
which are possible in SHARP APL. 


The word “function” is borrowed from mathema- 
tics, where it refers to a mapping between one set 
of values (the function’s domain) and another 
(the function’s range). In principle, it’s a process 
that is timeless, or instantaneous. At the instant 
that it receives an expression containing a function 
and its arguments, the system should supply a 
result. 


The word “program” connotes a sequence of 
events, separated in time and occurring one after 
another, and perhaps branching, looping, or 
repeating. A program may run continuously over 
an interval of time, receiving new input data and 
responding with new results, and continuing to do 
so indefinitely, or until told to stop, whereas a 
function is used at a single instant. 


This contrast in the connotations of “function” 
and “program” is clearest in the way each receives 
data. A function deals with the values of its argu- 
ments at the moment it is invoked, which is a 
single instant in time. A program may have to 
respond to a succession of events, and if so, cannot 
depend on the value of its argument at a single 
instant. It must also (or instead) have a means to 
receive a succession of values. A program charac- 
terized by sustained work over time typically 
receives information by using one or more vari- 
ables shared with events outside itself. 


Typically, an interactive program uses the symbols 
D or F to exchange information with the terminal; 
you can think of [ and 0 as variables shared with 
the terminal. Alternatively, such a program may 
receive new input from variables explicitly shared 
with another processor, or from files to which 
more than one task has access. The program 
MONITOR (which is listed in the chapter on shared 
variables) is an example; although it takes an ex- 
plicit argument, that argument is used only at the 
outset to establish its identity, and thereafter both 
input and output are made by way of the variables 
it shares with its partners. 


The result of a defined function: In an expres- 
sion such as Xx-Y, the value of X is multiplied by 
the result of -Y. Because the primitive function - 
returns a result, that result can become the argu- 
ment of x. The same is true of defined functions. 
It is possible to construct a Phrase that uses a 
defined function (such as 3xPROJECTED SALES) 
only when the function PROJECTED returns a re- 
sult. 


More generally, it is the ability to take an explicit 
argument and to return an explicit result which 
makes it possible to fit defined functions together 
into expressions. 


Distinction between terms “result” and “ef- 
fect”: In this manual, the word result is used 
to mean a result which can be passed to another 
function as its argument. Any other consequence 
of using a function is called an effect. For exam- 
ple, most arithmetic functions, such as X¥ xY, have 
a result but no effect. The function ?¥ produces 
an array of random numbers as its result and also 
has the effect of setting a new value to the random 
link ORL. The function ¥ DREPLACE Y has no re- 
sult, but has the effect of replacing a file compon- 
ent identified in Y with the value of X. 


Summarizing the contrast between “function” 
and “program”: The contrasts between them 
can be summarized as follows: 


1. Input 


A function works on data supplied as its argu- 
ment(s), which appears next to the name of the 
function in the statement that invokes it. 


A program receives data, perhaps repeatedly, 
from a variable (or from [ or M, or from a shared 
file) shared with another workspace or with the 
terminal. 


2. Processing 


A function is executed once, and its work ends 
when it has returned its result. 


A program may do that, or may run indefinitely, 
producing effects in response to new data, but not 
terminating. 


3. Result 


A function returns a result which may be used 
as the argument of another function in the same 
expression. 


A program may produce effects (including dis- 
plays, reports, etc.) but need not return a result 
usable by another function. 


Hybrids are quite possible. For example, a defined 
function to verify and edit data may accept as 
argument some proposed data, and return a ver- 
ified form of the data as its result. In between, it 
may engage in protracted exchanges with the ter- 
minal to display and correct the data. 


Use of the terms “function” and “program- 
ming”: In the foregoing discussion, the terms 
“function” and “program” are used to contrast 
alternative styles for supplied definitions, any of 
which may be appropriate to a particular situa- 
tion. In SHARP APL, the word “function” is 
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used to include all these alternatives; the command 
)FNS displays a list of all defined names, regard- 
less of their form or syntax. Similarly, the word 
“programming” is used in the APL community to 
mean the act of constructing a defined function, 
without regard to the form it takes. 


Alternate forms for the appearance of a defined 
function 


Standard display: The system displays a func- 
tion in a standard form, marked by the symbol V 
before and after each definition. The top line, cal- 
led the header, names the function and illustrates 
its syntax. The lines of the body are shown num- 
bered by consecutive integers, starting at 1, and 
enclosed in brackets. Here is the appearance of a 
simple function called GROWTHRATE: 


y Z<TIME GROWTHRATE RATE; R; T 
[1] R<0.01xRATH+12 
[2] T<TIMEx12 
[3] Z<(1+R)o.*T 

y 


“Publication forms”: APL may be used in si- 
tuations in which a computer system is not in- 
volved; for instance, it may be written on paper, 
on blackboards, etc., as a way of communicating 
with a human reader rather than a machine. In 
contexts where machine execution is not at issue, 
function definitions may appear without some of 
the trappings that are convenient in the machine. 
For example, although the system may show a 
definition with each line numbered, the line num- 
bers aren’t inherent to a function’s definition, and 
the published form may well omit them. Here’s 
how a function for the inverse of Kepler’s function 
is listed in the publication Starmap (APL Press, 
1978): 


Yy PSIE KEPLINVERSE TIME,ERFOR;TOL 
TOL*+0 .0000000001 
TIME*PSI<((pE),e TIME) pTIME 


The system function [CR (canonical representation 
of a function) omits both line numbers and the 
Y symbol, and shows the entire display left-jus- 
tified. 


A published form may also show lines connecting 
branch statements with their destinations, but 
these don’t appear in the definitions used by the 
machine. 


“Direct definition” form: Several writers on 
APL use a form they call “direct definition.” It 
is applicable only to definitions which are strictly 
functions (that is, take explicit arguments, return 
explicit results, and have no side effects). Using 
direct definition, a function may be represented by 
a single line. For example, the line 


R:iwita 


means that the function R is defined such that its 
result is obtained by dividing the right argument 
by the left argument. The name of the function 
appears at the left, followed by a colon. To the 
right of the colon, the definition appears, with the 
symbol w standing for the right argument, and a 
for the left argument (if there is one). 


Direct definition clearly requires you to think of 
a function primarily from the outside, and doesn’t 
concern you with such matters as internal names 
for the argument or result. 


SHARP APL does not directly support definitions 
written in that form. However, workspace 
2 DIRECTDEF simulates the effect of direct defini- 


' tion, by compiling definitions written in that way 


into the form the system uses. For examples of the 
use of direct definitions, see Iverson, Elementary 
Analysis, APL Press, 1977; Orth, Calculus in a 
New Key, APL Press, 1977; or McIntyre, “The 
Architectural Elegance of Crystals Made Clear by 
APL,” “Experience with Direct Definition One- 
liners in Writing APL Applications,” Proceed- 
ings, an APL Users Meeting, Toronto, 1978. 


TEST: >END IFA/,TOL>\ERROR+TIME-E KEPLERFN PSI 


PSI+PSI+ERROR:E KEPDERIV PSI 
>TEST 
END: PSI++/PSIx(2ppE)p(itpE) ti 
V 
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Alternate forms for the arguments and result 
of a defined function 


A user-defined function can have any of six possi- 
ble forms, depending on the number of arguments 
it takes, and whether or not it returns a result at 
the time it completes execution. The six possibili- 
ties are: 


Number of arguments 





A defined function which takes no argument must 
be used either alone, or in an expression in which 
the terms next to it are other functions; it can’t 
appear next to a data object or to another niladic 
function. 


symbol: 
there's 
going to 
be a result 


local 
del: name 
start for 
definition result 


left argument: 
local name for 
value you supply 


A function which takes one argument must be 
used with one argument, and its argument must 
appear to the right of it. 


A defined function which takes two arguments 
must appear with a right argument, but need not 
have an argument to the left of it. 


If it is to supply a value which will serve as the 
argument of another function, a user-defined func- 
tion must return a result. A function that does 
not return a result can only appear as the prin- 
cipal function of the statement in which it is used. 


The header specifies the syntax of a defined 
function: The definition of a function is divided 
into a single top line, called the header, and a 
sequence of numbered lines, called the body. 


symbol: 
local 
names 
follow 


right argument: 


name of local name for 
function value you supply 


local names 


V Z<TIME GROWTHRATE RATE;R;T 


steps to 
carry out 
function 


[1] R<0.01xRATE+12 
[2] T+<TIMEx12 
[3] Z4(1+R)o.* T 


V 


del: 
end 


definition 
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A function’s header contains the function’s name 
embedded in a paradigm which both illustrates the 
syntax the function is to have, and provides 
names to be used inside the function to refer to 
the values that are supplied as arguments, and 
from which the system will take the value it re- 
turns as the function’s result. 


The header shows the function’s name surrounded 
by zero, one, or two arguments. If the function is 
to return a result, to the left of the function’s name 
and arguments there appears the left-pointing 
arrow + and a local name for the result. 


The internal environment of a function 


While a function is being executed, certain names 
are local to it. As long as the function remains 
active, the local use of names supersedes any use 
they may have outside the function. The names 
provided in the header to refer to the function’s 
arguments and result, and any names used to label 
lines of the function’s body, are automatically local 
to it. 


You can make other names local to the function 
by listing them in the header, to the right of the 
paradigm, and separated from it and from each 
other by semicolons. It is good practice to localize 
any names used solely for temporary use within 
the function, to prevent the possibility of their con- 
flicting with other uses of the same name outside 
the function. You may also want to localize certain 
system variables (for example, the index origin 
OZO or comparison tolerance CT’) in order to pro- 
vide the function an internal environment different 
from that of the workspace around it. 


How a defined function receives its arguments: 
When you use a defined function which takes ar- 
guments, the argument is whatever data appears 
next to the function’s name. For example, if you’re 
applying the function F to data X, you write an 
expression that includes the phrase F X. 


In SHARP APL, arguments are passed by value. 


That is, the function F receives whatever value X 
currently denotes, but not the name X. 
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Inside the function, the system applies to the value 
thus received, whatever name the function’s header 
indicates as the name for the argument. 


GROWTHRATE 


N izimrives2 A 
GIZA). eT 


The value of a function’s argument thus crosses 
the boundary between what is outside the function 
and what is inside. Only the value crosses that 
boundary. Inside the function, the argument is 
referred to by the name shown in the header. Out- 
side, that value may have some other name, or no 
name at all. The function has no knowledge of the 
name its argument may have outside the function. 


(It may happen that the internal name for the 
argument is the same as the name used outside, 
but that is fortuitous; the names don’t conflict 
because the name of the argument is local to the 
function. ) 


See also the discussion of “Listing Names Visible 
at Each Level of the State Indicator” and 
“Sequence of Events When the System Starts 
Executing a Defined Function” in the chapter on 
“The Workspace Environment.” 


Mechanisms for creating and modifying 
defined functions 


There are several different ways to get the func- 
tion you want defined in your workspace: 


1. Load a workspace that contains it. That’s 
most appropriate when there is a public library 
containing functions that fit your needs. 


2. Use the command )COPY to bring the func- 
tion’s definition from a saved workspace. The 
saved workspace may be your own, somebody 
else’s, or a public workspace. 


3. Use direct definition functions provided in 
the workspace 2 DIRECTDEF to compile a func- 
tion from a character array containing its direct 
definition (which you may write, or copy from 
elsewhere). 


4. Use the system function DPDEF to define a 
function from the contents of a package. The 
package may in turn be one that you copy from 
another workspace or read from a file. 


Note that if you use (PDEF at a time when the 
function’s name is localized, you thereby create a 
local function, which remains in existence only as 
long as the function to which it is local remains 
active. 


You can’t use []PDEF to create a function definition 
if a function of that name already exists and is 
active (that is, appears anywhere on the state in- 
dicator). 


5. Use the system function [FX or 3 DFD to 
create a function from a character array that 
you write (or copy from elsewhere). 


You can’t use 3 DFD if a function with the same 
name already exists; you must first expunge the 
existing definition. You can’t use either 3 DFD or 
OFX if a function of that name already exists and 
is active (that is, appears anywhere on the state 
indicator). 


Note that if you use either OFX or 3 DFD at a time 
when the name of your function is localized, you 
will thereby produce a local function, which will 
exist only as long as the function to which it is 
local remains active. 


6. Use the symbol V (“del”) to invoke the 
system function editor. The function editor can 
be used either to create a new function or to 
modify an existing one, but either way it refers 
always to global functions, and can’t be used to 
create, edit, or display a local function. 


You can use the del editor to edit an active func- 
tion, and then resume its execution. The del editor 
is the only mechanism that permits you to resume 
execution at the point where work was interrupted 
(rather than starting over from the beginning). 
However, you can use the del editor only when 
the function appears only once on the state indica- 
tor, as the most recently invoked function. 


Watch out: If you have a local function of the 
same name as a global function, and execution is 
halted inside the local function, using the del edi- 
tor will refer not to the function that’s suspended 
but to the global one. 


Advantages and disadvantages of the del func- 
tion editor: The V editor is designed for interac- 
tive use at a terminal. It contains a powerful line- 
editing facility. That makes it easy to insert 
modifications to a line of a definition. The del 
editor is the only mechanism which permits you 
to edit a function that remains active, and hence 
is the recommended tool for dealing with errors 
you encounter during trial use of a new definition. 


On the other hand, the V editor can be invoked 
only from the keyboard, whereas functions such as 
OPDEF, DFX or 3 DFD can be invoked by other 
functions, and thereby provide automatic function 
creation, function editing, or function overlay. 
They also make possible compilers such as the one 
in 2 DIRECTDEF to create definitions acceptable 
to the system from alternative forms that could not 
otherwise be used. 


Procedures for using the del editor are described 
in the chapter on “Modes of Interaction at a Ter- 
minal.” Procedures for using DPDEF are described 
in the chapter on packages and on the definition 
of package functions. Procedures for using OFX 
and 3 (FD are described in the chapter on 
“System Functions for Function Definition.” 
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Chapter 7: 


THE WORKSPACE 
ENVIRONMENT 





THE WORKSPACE ENVIRONMENT 


All computation takes place in the active work- 
space. There is one active workspace for each 
task—that is, for each person using the system 
from a terminal, and for each task active without 
a terminal. 


A workspace is an environment within which 
names have meanings. You could compare it to a 
chalkboard or to a notebook, initially empty, but 
in which names and their meanings can be record- 
ed. 


Each workspace contains a symbol table. The 
symbol table contains an entry for each name in 
use in the workspace, together with an indication 
of the type of thing named, and a pointer to the 
place within the workspace where the APL system 
can find the named thing. As a user, you can see 
neither the symbol table itself, nor the spatial 
layout of the workspace. You don’t need to. All 
you can do—all you need to do—is assign names 
to data or functions, and refer to them by name. 
You become aware of the fact that this requires 
physical storage space only by asking for the 
amount of work area remaining (by the system 
function [WA) or by encountering the message 
WS FULL, which means that there’s not enough 
space to carry out the calculation you've requested. 


Names in the workspace 


The workspace contains the names and meanings 
of three classes of things: 


Variables 
Functions 


Labels 


(A name may also refer to a group. Groups are 
now considered obsolete, but the SHARP APL 
system continues to tolerate them. A group was a 
list of names to be treated together by the system 
commands )COPY and )ERASE.) 


Names may be declared to be local to a function. 
The meaning of a local name is visible only while 
the function to which it is local is being executed; 
see the discussion of “Local and Global Uses of 
Names.” 


The way in which you assign a name to an object 
depends on whether it is a variable, a function, or 
a label. 


Variable: You assign a name to a variable as a 
side-effect of using the specification arrow +. The 
name can’t be a name having a visible use as a 
label or as the name of a function. 


Function: You assign a name to a function as 
a side-effect of the function OFX , or of certain uses 
of the function QFD. You can also assign a name 
to a function by entering from the keyboard the 
symbol V followed by a header indicating (among 
other things) the name the function is to have; that 
procedure can only be started from the keyboard 
during execution mode, and can only be used to 
create a global function. 


There are certain restrictions on what use (if any) 
the name may have had in the workspace before 
you use it as the name of a function. These restric- 
tions are slightly different for functions formed 
with V, with OFX, or with DFD, as described in 
the preceding chapter, and in the chapter on “Sys- 
tem Functions for Function Definition.” 


Label: A label is a name used to refer to a par- 
ticular line of a function’s definition. It gets its 
value indirectly, as a side effect of executing the 
function. The value of a label is the position of 
the line on which it occurs within the function’s 
definition. While the function is being used, it ap- 
pears as a named constant whose value is the 
number of the line to which it is attached. A 
named constant looks like a variable, but you can’t 
alter its value. A label is local, and is visible only 
while the function in which it occurs is being 
executed. As a practical matter, the names used as 
labels in a function must be distinct from the 
names of any functions or variables to which the 
definition refers. 


Local and global uses of names 


A global object is one that exists in the workspace 
even when no defined function is being executed. 
Its name is said to be a global name. By contrast, 
a local name is a name that belongs to a par- 
ticular function and is effective only while that 
function is being executed. A local name is ex- 
plicitly declared to be local by appearing in the 
header of the function’s definition, or implicitly 
declared to be local by appearing as a label within 
the body of the definition. While a function is 
being executed, the local meaning of each of its 
local names (if any) “shadows” the meaning that 
each of those names might have outside the func- 
tion. 


One defined function can make reference to anoth- 
er. For example, a function called F1 could con- 
tain within it a reference to a defined function 
called F2. In that case, the system will start 
executing F2 before it completes execution of F1. 
Names local to F1 will then appear to be global 
to F2. 


Names local to a function are global to any func- 
tions it invokes. Those functions may in turn call 
others; for example, F2 may contain a reference 
to F3, and so on. At each level, names localized 
within a function are global to any functions it 
calls. 


It is possible for a single name (if it occurs as a 
local name in functions that call each other) to 
have many different meanings, a new meaning 
taking effect at each level at which the name is 
localized. 


All names appearing in the header of a function 
(other than the name of the function itself) are 
local to the function. That includes the names used 
for the function’s result and for its arguments, and 
all additional names listed further to the right (set 
off from the rest of the header and from each other 
by semicolons). The list of local names may in- 
clude the names of system variables (but not of 
system functions). It may also include the name 
of the function itself (in which case it can’t be 
reinvoked until its first execution has been com- 
pleted). 
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Y 


funcuon 3 





funcuon 2 





function | 





ACTIVE WORKSPACE 





The system command )SIV gives a list of the 
functions whose executions are in progress, and 
the names local to each. 


At any moment, only one meaning of a name is 
visible. The meaning which is visible to an APL 
expression is always the most local meaning. 


Visible use of a name 


Read down to first level at which each name is 
used. Levels below are shadowed. 





names 
TAX TIME RATE 





+ 
RATE 








FUNCTION 3 
FUNCTION 2 RATE 
FUNCTION | TIME RATE 





= 


no function | TAX 














Watch out: Although an APL expression always 
refers to the visible—that is, the most local— 
meaning of a name, each of the system commands 
\COPY, )PCOPY, )GROUP and )ERASE or the func- 
tion-editor V always refers to the global use of 
a name, even when the global meaning is invisible 
to an APL function because of localization. For 
example, the system command )ERASE Y would 
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erase the global meaning of Y even when the 
current visible meaning of Y is a local. Similarly, 
VY would open the definition of a global function 
named Y, even when the visible use of Y is a local. 
The function 5 [WS reports the type of use a 
name has at all levels of localization. The system 
may make use of all levels of use of the system 
variable QTRAP. 


Well-formed names 


Within your active workspace, a name may refer 
to a variable, a function, or a label. (A file also 
has a name and so does the workspace, but those 
names don’t refer to anything inside the work- 
space. ) 


A name must start with an alphabetic character. 
An alphabetic character is any of the letters A to 
Z, or of the underlined letters, A to Z. If a name 
has more than one character, the remaining char- 
acters may be any alphabetic character, or any of 
the digits 0 to 9. The system also accepts the char- 
acter A and its underlined form A as alphabetic 
characters. 


A name may not contain a blank, nor the under- 
bar character alone, nor any other symbol. A name 
may not begin with the characters SA or TA. 
Those two prefixes are reserved for use in setting 
“stop” and “trace” controls (see the chapter on 
“System Functions for Function Definition”). 


A name used within an APL workspace (that is, 
the name of a variable, function, or label) may 
have up to 77 characters. The name of a work- 


space or file may have up to 11 characters. If you 
use a name longer than the permissible maximum, 
the extra characters are ignored, except by the file 
functions, which regard a too-long name as a 
DOMAIN ERROR. 


Each of the following lines shows a single valid 
name: 


X 

COSTS 
COSTS78 
COSTAESTA78 


Each of the following lines shows characters that 
could not form a single valid name: 


78COSTS 
TEMP .FILE 
TEMP FILE 
PRICEXQUAN 


Distinguished names are used for system vari- 
ables and system functions: The system attach- 
es special significance to certain names, referred 
to as “distinguished names.” A distinguished name 
is distinguished by the fact that it begins with the 
symbol D, whereas [ is not otherwise permitted as 
a character in a name. Distinguished names are 
used to refer either to system variables or to 
system functions. The set of distinguished names 
is fixed by the system; you can’t coin a new distin- 
guished name. 


A system variable is one that affects some aspect 
of the workspace environment or of the way in 
which the system carries out its work or commun- 
icates with you. For example, the system variable 
DZO determines which number is considered to be 
the first index number; its possible meaningful 
values are 0 or 1. The system variable DPW deter- 
mines the maximum print width in the prepara- 
tion of displays for the terminal. You can give new 
values to system variables as your work requires, 
and thereby influence the system’s behaviour. 


A system function is a primitive function that you 
can use either to report to you some aspect of the 
system’s work, or that permits you to transmit to 
the system certain kinds of requests. For example, 
the system function DZC reports the current values 
of the line counter within the workspace, and the 


system function DTS reports the current value of 
the system timestamp. The system function [RUN 
instructs the system to start an N-task, and the 
system function [ZOAD instructs it to load a work- 
space. 


You can specify a new value for a system variable. 
But you can’t use a distinguished name as the 
name of a defined function or a label. However, 
the name of a system variable (but not a system 
function) may be made local to a function defini- 
tion, and may be used as the name of the argu- 
ment or result of a defined function. 


Over the last few years, there has been a gradual 
tendency for system variables and system functions 
first to duplicate and then to supplant the system 
commands. An important difference between dis- 
tinguished names and system commands is that 
distinguished names may be used by a statement 
within a defined function, whereas system com- 
mands may only be entered manually from the 
keyboard. 


The various system variables and system functions 
are listed in the discussions of the topics to which 
they are relevant. Each is defined individually in 
one of the chapters devoted to the class of object 
to which it belongs. 


Reporting the environment in the active work- 
space 


Certain system functions permit you to inquire 
about aspects of the internal state of the active 
workspace. Other aspects are under your direct 
control, since you can set values of the system 
variables that control them. The following system 
functions report aspects of the environment of the 
active workspace: 


ows Dyadic; depending on the arguments, re- 
ports the state indicator, the names that 
are in use, the type of use to which 
names are put, the size of the symbol 
table, and so on. 


OWA The remaining work area in the work- 
space, in bytes. 


oze The number of the line currently active 
for each active function. 
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A list of the functions whose execution has been 
started but not completed can be obtained either 
as the result of the system function 2 DWS 2, or 
by using the system command )SI. The expression 
2 [WS 2 returns as its result a character matrix, 
while the command )SI causes an equivalent dis- 
play at the terminal. The display is arranged in 
the order in which the functions were invoked, 
with the most recently invoked function at the top. 
The system function [WS is described in the chap- 
ter entitled “System Functions for Reporting 
System or Workspace Information.” 


The state indicator and the line counter are not 
variables under your direct control; rather, they 
are indicators of the state of affairs brought about 
by your use of defined functions. 


Status of work in progress in the workspace: 
Each workspace contains a state indicator and a 
line counter. Together, these show the name of 
the function now active, and the line of that func- 
tion that is being executed. They also show the 
function that invoked the active function, and the 
function that invoked it—for as many functions as 
are active. The state indicator contains a line for 
each defined function whose execution has been 
started but not yet completed. It also shows the 
symbols ¢ and [ in the same manner as defined 
functions. 


When the active workspace is saved, the line coun- 
ter and state indicator are saved as part of it, so 
that, if the saved workspace is loaded at some later 
occasion, it is recovered as it was. If it’s appro- 
priate, you'll be able to resume execution where 
it was suspended. 


Pendent vs. suspended functions: A function 
whose execution has been suspended (because of 


an interruption or an error) is said to be suspend- 
ed. 


A function which appears in the state indicator but 
which is not suspended is said to be pendent. 
Although it isn’t currently active, there’s nothing 
wrong with it; it’s simply waiting until execution 
of the function that it invoked is completed. Execu- 
tion of a pendent function resumes automatically 
as soon as execution of the function above it in the 
state indicator is completed. 
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The result of 2 OWS 2 (or the display produced 
by )SI) shows on each row the name of a func- 
tion, followed in brackets by the number of the 
current line. A suspended function is marked by 
an asterisk, whereas a pendent function has no 
asterisk. 


The line counter: The niladic system function 
OLC returns a numeric vector having one element 
for each row of the state indicator; it contains in 
numeric form the line numbers shown in brackets 
in the display of the state indicator. 


For a pendent function, the line number shown is 
the number of the line now being executed. For 
a suspended function whose execution was halted 
by an error or interrupt, DZC shows the number 
of the line the system was executing when the 
error or interrupt occurred. For a function halted 
after execution of one line has been completed, but 
before execution of the next line has started, DZC 
shows the number of the line next to be executed 
if execution is resumed in sequence. 


When the system puts the symbols 2 and [] on the 
state indicator, the corresponding elements of [ILC 
contain the number 0. 


Resuming execution of the most recently 
suspended function 


When a function has been suspended, the system 
waits for you to indicate what you want done with 
it. The system does not abandon it. You don’t 
have to resume execution at once; you're free to 
start execution of any function whose definition is 
visible. Those new function calls will appear at the 
top of the state indicator, above the entries that 
show the suspended function. 


When ready, you can instruct the system to re- 
sume execution of the suspended function at the 
top of the state indicator. You do that by entering 
from the keyboard the statement 


Lc 


(or, if you want to resume at some other state- 
ment, enter > followed by the label or line num- 
ber of the line you want). 


The only function whose execution can be re- 
sumed in that way is the suspended function at the 
top of the state indicator. A branch statement al- 
ways refers to the function at the top of the state 
indicator. Thus, the only way ever to resume a 
pendent execution is to resume execution of the 
suspended function for which the pendent function 
is waiting. 


Watch out: The expression +10 (or any branch 
whose destination is empty) means “continue in 
sequence.” When entered from the keyboard, or 
in a trap definition, it is equivalent to +9ZC+1 
rather than to ~[JZC. 


Listing names visible at each level of the state 
indicator 


At each level of the state indicator (except those 
corresponding to use of the symbols ¢ or Q), names 
may have been localized. The system command 
)SIV gives you a display like the one produced by 
)SI, but showing on each row a list of the names 
localized in that function. That includes the names 
used for the function’s argument(s) and result, 
names used as labels, and any other names ex- 
plicitly mentioned in the function header. There 
is no system function that directly produces an 
analogous result. 


The system function 5 DWS takes as its argument 
one or more names, and gives you back a table 


showing what use is made of each name at every 
level of the state indicator. For a detailed descrip- 
tion of the function, and an example showing the 
report it generates, see the section entitled “Work- 
space Information: State Indicator” in Chapter 25. 


Control of the workspace environment 


Some aspects of the workspace environment can be 
altered. These include such things as index origin, 
print precision, print width, and comparison toler- 
ance. These are represented by system variables. 
You can, if appropriate, set a new global value for 
any of these system variables. Alternatively, you 
can make their names local to a particular function 
and include in its definition, statements that assign 
to them the values you require. That way, when 
execution is complete, the former global values 
will again be visible. 


In a clear workspace, the system variables that 
affect the workspace environment are automatical- 
ly assigned default global values. If need be, those 
global values can be respecified. Initially a work- 
space contains the default values without any 
specific action on your part. 


The following system variables are part of the 
workspace environment. Each may be made local 
to a function, but when you do that, note that the 
variable will have no value at all until some state- 


Index origin: First counting number; 0 or 1. 


Print precision: Number of significant digits in display. 


Print width: Number of printing positions on a line. 


Random link: Used in generating next random number. 


Comparison tolerance: 


Latent expression: 
workspace is loaded. 


Permissible relative error in Judging equality. 


Expression to be executed automatically when a 


The meaning and effect of each of these system variables is discussed under its individual entry 
in the chapter devoted to the class of system variable to which it belongs. 
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ment within the function gives it one. The default 
global value in a clear workspace for each of these 
system variables is shown. (Description of the ef- 
fect each has is given separately, or accompanies 
the description of the topic it affects. ) 


Sequence of events when the system starts 
executing a defined function 


Arguments are passed to a function, and results 
returned, by value. The argument of a function 
is whatever value results from evaluating the 
expression to the right or left of it. Notice that as 
long as a function works satisfactorily, you never 
need to know what names it uses for its arguments 
or its result, or what other names it may localize. 
These become significant only when you halt the 
function or change its definition. 


When the system starts to execute a defined func- 
tion, the following things happen: 


1. The system puts the function’s name at the 
top of the state indicator list of functions being 
executed. 


2. The system appends to the front of the DLC 
vector a number that indicates which line in this 
function is next to be executed. Initially, this num- 
ber is 1. Later, as execution of the function 
progresses, the number in the first element of 
LC is revised so that it always shows the line now 
in process or ready to be processed next. Note that 
the first member of DLC always refers to the “in- 
nermost” function—that is, the one most recently 
started. 


3. The system creates variables to contain the 
values of the arguments. Note that it doesn’t mat- 
ter by what names the arguments were known 
outside the function (or even whether they had 
names at all). The names of the arguments are 
local names. As long as the execution of this func- 
tion remains incomplete, they supersede any global 
meanings those names may have. 


4. All other names appearing in the function 
header are local. That is, they have no meaning 
until assigned one during execution of the func- 
tion. However, this does not apply to the name of 
the function itself unless that name is explicitly 
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repeated in the list of local names, or is also used 
as the name of a label, an argument, or the result. 


5. The system gives each of the labels in the 
function a value corresponding to the number of 
the line on which the label occurs. A label differs 
from other local variables in that (a) it gets its 
value automatically at the start of function execu- 
tion, and (b) its value can’t be respecified. 


Any object outside the function, but having the 
same name as an argument, result, label, or local 
name of the function, is invisible while the func- 
tion is being executed. 


The system executes the lines of the function in 
sequence (or as branch statements may direct) 
until the function ends. At that point, the value 
of whatever variable was named in the header as 
the result of the function is returned. The first 
element of OZC is dropped, and the function’s 
name is removed from the state indicator. The 
meanings of all names local to the function vanish. 
The earlier (more global) meanings of those 
names (if there were any) become visible once 


more. $y 


Chapter 8: 


THE STRUCTURE 
OF DATA 





Arrays and packages 


Generally speaking, an APL data object is an 
array, that is, a collection of numbers or charac- 
ters organized into a rectangular structure having 
any number of axes. 


SHARP APL also permits several otherwise un- 
related names to be enclosed to form a package. 
A package is a single data object without structure; 
the language provides functions to extract from a 
package some or all of the names within it. A 
package thus provides a means to store or transmit 
diverse objects as a single unit. An ordinary array 
may not contain a package; in this manual, pack- 
ages are discussed separately from array data. 


Structure of a data array 


An array is a rectangular collection of data. When 
an array is named (that is, when it is a variable), 
the name refers to the entire array. Each of its 
elements is a single number or a single character; 
at present an element can have no further struc- 
ture. 


For the present, SHARP APL is restricted to sim- 
ple arrays. A simple array is one in which each 
element is a single number or a single character. 
By contrast, a nested array is one in which an 
individual element may itself be an array. The 
APL community has devoted much discussion to 
nested arrays, and SHARP APL is expected to 
include them. But for the present the system does 
not permit nested arrays, and there is no further 
mention of them in this manual. 


The system requires that all the elements of a 
simple array be of the same type. That is, either 
all of them must be numbers, or all of them must 
be characters. 
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Any reference to an array is a reference to the 
array as a whole, and thus refers to all of its 
elements. This often makes it possible to process 
all of the elements of an array without having to 
write an explicit iteration. However, when you 
need to refer not to the whole array but to certain 
elements within it, you can select the sub-array 
that concerns you at the moment. 


Structure and value: Every array has both 
structure and value. “Structure” refers to the 
spatial framework of positions in which the values 
are located. The existence of the structure makes 
it possible to refer to particular parts of an array 
by the locations at which they are found. “Value” 
refers to the particular number or character found 
at each position within the array. 


Structure and value always exist together. That is, 
whenever a data array exists, it must have a struc- 
ture and each element in its structure must have 
a value. Whatever numbers or characters an array 
contains must be arranged in some spatial struc- 
ture, and every position within that structure must 
contain some value. 


An element within an array can be identified by 
describing its position on each of the axes (or 
“dimensions” or “coordinates”) of the array. For 
example, a matrix (or table) is an array having 
two axes, rows and columns. To identify a single 
position within such a two-axis array, you have 
to state its position on each of those two axes. 


The rank of an array 


The rank of an array is the number of axes it has. 
An array may have any number of axes. It may 
even have zero axes; in that case, it has room for 
only one number or character, and it is unneces- 
sary (and impossible) to specify any positions 
within it. While in principle an array can have as 
many axes as you wish, as a practical matter, the 
system limits you to arrays that have no more than 
63 axes; applications don’t often require more than 
two or three axes. 
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Special terms are in use for arrays of certain com- 
mon ranks: 


Rank 0 Scalar 
Rank 1 Vector (or “string” ) 
Rank 2 Matrix (or “table” ) 


Rank 3 and up 


No special name (sometimes 
“Rank-3 array” or “3-D 
array”) 
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The shape of an array 


An array is rectangular. The shape of an array 
is the length of each of its axes. Thus, the shape 
of an array of rank n can be described by a vector 
of n numbers. 


Because every array is rectangular, if for example, 
a matrix has a dozen rows, every one of those rows 
must have the same length as all the others. You 
can’t create a ragged array in which the first row 
has ten elements, the second two, and the last 
nineteen. (If your data seem to require ragged 
storage, there are various ways of keeping track 
of items of different size within the overall frame- 
work of rectangular arrays.) 


When the monadic function shape, denoted by the 
symbol p (rho), is applied to a data array, it 
returns a numeric vector containing as many ele- 
ments as the array has axes. The value of each 
element is the length of the corresponding axis. 


The total number of elements in an array is the 
product of the lengths of its axes. For an array 
X, that is x/pX. Since the result of pX has one 
element for each axis of X, the rank of X can be 
obtained from ppX. 


Applying a primitive function to all elements 
of an array 


A primitive function that is one of the scalar func- 
tions can accept as argument any array, regardless 
of its rank or shape. The system applies the func- 
tion independently, in parallel fashion, to each of 
the elements. Such a function is called a scalar 
function because it is defined on a scalar argument 
(or a pair of scalar arguments) and returns a 
scalar result. Applied to an argument that is an 
array having rank greater than zero, a scalar func- 


tion is applied independently to each of the argu- 
ment’s elements. 


Not all functions are scalar functions. Some re- 
quire an argument limited to an array of a partic- 
ular rank or shape, while others attach a particu- 
lar significance to one or more of the axes. 


The result produced by applying a monadic scalar 
function to an array of any rank or shape is an 
array having the same rank and shape as the argu- 
ment. 


A dyadic scalar function is subject to certain res- 
trictions. The arrays that are its arguments must 
conform in rank and shape. Conformability is dis- 
cussed in the section “The Concept of Confor- 
mability.” 


A dyadic scalar function may be modified by three 
powerful —_ operators—scan, reduction, and 
product—to produce an important class of derived 
functions. The use of these operators with dyadic 
scalar functions is described in the chapter entitled 
“Dyadic Operators.” Rules governing dyadic 
scalar functions without operators are described in 
the chapter entitled “Dyadic Scalar Functions.” 


Applying a scalar dyadic function to array ar- 
guments 


A dyadic scalar function, like a monadic scalar 
function, is applied in parallel fashion to the ele- 
ments of a pair of arrays. Familiar dyadic scalar 
functions include multiplication, division, addition, 
subtraction, etc. 


When a function takes two arguments, the two 
arrays must correspond in rank and shape so that 
it is apparent which element of one is paired with 
an element of the other. A pair of arrays that 


satisfies this requirement is said to be conform- 
able. 


A dyadic scalar function is applied to a pair of 
array arguments element by element. The argu- 
ments must have the same rank and shape (except 
as noted below). The result has the same shape 
as the arguments. Each element of the result is 
formed by applying the function to the correspond- 
ing element of the left argument and the corre- 
sponding element of the right argument. 


Either both arguments must have the same rank 
and shape, or one argument may have a single 
element, in which case it is treated as though that 
element were replicated throughout an array 
matching the other argument in rank and shape. 
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Two types of array data 


Data arrays are of two main types: character and 
numeric. Characters and numbers may not both 
appear in the same simple array. This restriction 
is not inherent in the APL language, but is a 
requirement widely adopted in APL systems as a 
way of simplifying implementation. 


Empty arrays 


The length of one (or more) of the axes of an 
array may be zero. In that case, the array is said 
to be empty. You can generate an empty array as 
the result of a computation (for example, selecting 
by a test that is met by none of the elements in 
an array). Empty arrays are often used as the 
initial value for an array to which further elements 
will subsequently be joined as they are found. 


For most purposes, an empty array has no type. 
That is, it is not significant whether you think of 
it as an empty array of numbers or as an empty 
array of characters. However, two functions (ex- 
pand and take) can under some circumstances 
create an array containing more elements than 
were provided in the argument. The extra ele- 
ments thus created have the value zero in a 
numeric array, and the character “blank” in a 
character array. If you apply “take” or “expand” 
to an empty array, your result contains either 
numeric zeros or character blanks, depending on 
whether the empty array was created as an empty 
numeric array or as an empty character array. 


Display of an empty vector produces one blank 
line (that is, a line on which no characters or 
numbers are displayed). Display of an empty 
array of rank 2 or greater produces no printing 
at all. 


The order of axes 


All functions which refer to the shape of an array 
treat the axes in the same order. Where there are 
two or more axes, the last axis is columns, and the 
next-to-last axis is rows. Thus, an array whose 
shape is 7 12 is a matrix with seven rows and 
twelve columns. 
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In an array having more than three axes, the 
second-from-last can be thought of as planes or 
perhaps slices, the third-from-last as hyper-planes 
or perhaps blocks, and so on. However, it isn’t 
important to maintain geometric or spatial mean- 
ings to these higher dimensions; it is sufficient that 
axes are always treated in the same order. The 
function & (transpose) permutes the sequence of 
axes of a data array. 


Functions that form arrays 


APL does not use the declarations required in lan- 
guages such as FORTRAN or COBOL. An array 
acquires structure and value simultaneously. Thus, 
each function that forms an array does so by re- 
shaping (in one manner or another) an array that 
already exists (coming, ultimately, from a constant 
supplied by the author or user of a function). In 
this chapter, the functions that may be used to 
form an array are listed briefly. Each is described 
in greater detail in the portion of this manual 
devoted to definitions of primitive functions. 


Ravel: Denoted by monadic use of the symbol 
, (comma). The expression ,X forms a vector 
containing all the elements of the array X, in row- 
major order. 


Reshape: Denoted by dyadic use of the symbol 
o (rho). The expression SpX forms an array 
whose shape is specified by the vector S, and 
whose values are taken from the array X (in row- 
major order). 


Take: Denoted by dyadic use of the symbol + 
(take). The expression S+X forms an array of the 
same rank as X, but with its length along each axis 
formed by taking from X the first (or last, when 
S is negative) positions specified in 5. 


Drop: Denoted by dyadic use of the symbol + 
(drop). The expression 5+X forms an array hav- 
ing the same rank as X, but with a length along 
each axis formed by dropping from X the first (or 
last, when S is negative) positions specified in S. 


Transpose: Denoted by monadic or dyadic use 
of the symbol & (transpose). The expression PQX 
forms an array in which the sequence of the axes 
is permuted; the length of each axis is unchanged. 


The left argument P specifies the new sequence of 
each of the axes of X. If & is used monadically, the 
result has the axes in reverse order. 


Reverse: Denoted by monadic use of the symbol 
$ or © (reverse). The expression OX creates an 
array with the same shape as X, but with the 
sequence of elements along one axis reversed. 


Rotate: Denoted by dyadic use of the symbol > 
or © (rotate). The expression NX creates an array 
having the same shape as X, but with the positions 
along one axis rotated by N positions. 


Compress: Denoted by dyadic use of the 
symbols / or # (compress) when the left argument 
is Boolean. The expression P/X compresses one 
axis of X by deleting those positions at which the 
proposition P is false. 


Expand: Denoted by dyadic use of the symbol 
\ or \ (expand) when the left argument is 
Boolean. The expression P\X expands the length 
of one axis X by inserting fill values (zero or 
blank) at the positions where the proposition P is 
false. 


Index: Denoted by [ ] (brackets) following a 
data array. An expression such as X[A;B;C] 
selects from X the elements whose positions along 
the first axis are given by A, and along the next 
axis by B, and so on; expressions for the various 
axes are separated by semicolons. 


Catenate/Laminate: Denoted by dyadic use of 
» (comma). The expression X,Y forms an array 
by joining the arrays X and Y along one axis. This 
is called “catenation” when they are joined along 
an existing axis, and “lamination” when they are 
Joined along a new axis. 


Structure of a package 


A package contains a set of names. In that respect 
it resembles a workspace. However, a package 
doesn’t contain anything corresponding to the state 
indicator of a workspace. A package may contain, 
“packed” within it, any number of names. With 
each name, there may or may not be an object 
to which the name refers. An object can be refer- 
red to only by its name. It can be used only after 


it has been extracted from the package and re- 
created in the workspace; that is done with the 
functions QPDEF or QPVAL. 


The various objects within a package may be of 
different types; for example, one of the named 
objects in a package might be a data array, anoth- 
er might be a defined function, while another 
might be a package. A package may contain a 
package. There is no spatial or sequential order 
of the names within a package; in particular, a 
package does not have axes. 


SHARP APL contains a number of primitive 
functions for making use of packages. These in- 
clude functions to form a package from a list of 
named objects present in the active workspace. It 
also includes functions to define (“unpack”) some 
or all of the objects within a package; this causes 
those objects again to exist in the workspace. 
Other functions merge two packages to form a 
single package, or report the names a package con- 
tains. 


A note about semicolons and lists 


In certain situations it’s possible to refer to several 
arrays in what is informally called a list. A list 
is a sequence of two or more expressions, each 
separated from the next by a semicolon. Each of 
those expressions, when evaluated, gives rise to an 
array. A list is thus a way of referring to several 
different arrays at once, but without Joining them 
together to form a single array. The situations in 
which it’s permissible to do that are: 


1. Indexing: Indexing requires you to supply 
index numbers separately for each axis of the 
array being indexed. If the array has more than 
one axis, then you need more than one array of 
index numbers. The arrays of index numbers are 
stated as a list; the entire list is enclosed in brack- 
ets. This is described further in the discussion of 
the index (to subscript) function in the chapter 
entitled “Non-scalar Primitive Functions (Other 
Than System Functions).” 


2. Formatting: The function DFM? gives you a 
character matrix showing data in a format 
specified in the left argument of [FMT. You can 
take the data to be formatted from more than one 
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array. In that case, the various arrays to be for- 
matted appear as a list in the right argument of 
OFMT; the entire list is enclosed in parentheses. 


3. “Mixed output”: At present, SHARP APL 
continues to tolerate a form of display called mixed 
output. However, mixed output is considered ob- 
solete; the effects it produces are better obtained 
using the formatting primitives ¥ and DFMT. A 
statement consisting solely of a list (that is, a 
sequence of expressions separated by semicolons ) 
means that the various expressions are to be print- 
ed, one after the other, from left to right across 
the page (or screen). 


These three are the only uses of expressions separ- 
ated by semicolons. (Semicolon is also used to 
separate names in the header of a function defini- 
tion.) 


Notice that semicolon is not a function, and does 
not produce a single array as a result. You can’t 
assign a list to a variable, and you can’t use a list 
as the argument of any function other than index- 
ing (surrounded by brackets) or [FMT (surround- 
ed by parentheses). 


The semicolon has the anomalous property that it 
acts as a complete separator between expressions, 
so it is mot necessary to enclose the individual 
expressions in parentheses. For example, the fol- 
lowing are equivalent: 


2xA3+7#B;C < (2xA)3(4+7B)5C 


Assigning significance to particular axes 


The meaning you attach to each axis of an array 
is quite arbitrary. You can arrange data any way 
you want. However, APL includes facilities that 
make certain arrangements convenient. 


The functions produced by the inner product oper- 
ator are extensions and generalizations of matrix 
algebra. In APL you can state directly a great 
many expressions familiar in disciplines in which 
an array of data is customarily represented as a 
matrix, and in which algorithms are represented 
in the notation of matrix algebra. In APL, matrix 
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algebra is extended and generalized to include ar- 
rays of any rank, and the inner product is gener- 
alized to include pairings of any two scalar dyadic 
functions, not just + and x which underlie the 
ordinary matrix product. These generalizations 
available in APL permit many data processing 
topics that were not previously treated in that way 
to be concisely represented by functions on ma- 
trices or multi-axis arrays. (See the discussion of 
the inner product operator, and of matrix multi- 
plication, matrix division, and matrix inverse.) 


The extended matrix functions available in APL 
are best exploited when you organize the structure 
of your data arrays to take advantage of them. 
This usually requires that a particular axis (com- 
monly the first or last) is devoted to some sort of 
explicit representation of the data described by 
the other axes. Such a representation might be the 
coefficients of each of a set of polynomials, or the 
quantity of each possible component required to 
manufacture an item, or the successive characters 
required to spell a name, or the distance or travel 
time from one city to other cities, and so on. 


One form of such explicit representation may be 
generated directly by the encode function T, which 
creates an array having one (or more) new axes 
(ahead of the first axis of the argument) contain- 
ing the representation (in some number system) 
of each of the elements of the argument. The func- 
tion 1 (“decode,” in some respects inverse to T) 
evaluates an array of such explicit representations. 
Because number systems are based on polynomial 
representations, evaluating numbers represented in 
various bases is the same thing as evaluating poly- 
nomials. The existence of number representation 
primitives makes it particularly convenient to ar- 
range data so that an explicit representation (for 
example, the coefficients of a polynomial) is the 
first axis of an array. Such applications are dis- 
cussed briefly in the discussion of the functions 1 
(base value, or decode) and T (representation or 
encode). 


In similar fashion, the inner product operator 
creates a family of functions which make it con- 
venient to choose axes so the last axis of one array 
has a direct correspondence to the first axis of 
another. If the corresponding axis is not in the 
position you want, you can always apply a suitable 
transpose to permute the order of axes. 


As an example, suppose the variable PLAN is a 
2-axis array showing the number of each product 
to be manufactured at each of several factories. 
Suppose PLAN is arranged so that the first axis 
(rows) indicates the factory and the second axis 
(columns) the product. Suppose further that 
PARTS is an array showing the number of com- 
ponent parts required to make each product, ar- 
ranged so that the first axis corresponds to 
products, and the second to parts. The fact that 
the last axis of PLAN has the same significance 
(and length, and order) as the first axis of 
PARTS can be directly exploited in the inner 
product PLAN+.xPARTS, which calculates for each 
factory the total number of parts required for its 
planned production. 


Similarly, suppose NAMETABLE is a character ma- 
trix of names, arranged so that the first axis is 
products (or people, or whatever) and the second 
axis is the successive characters of their names, 
and suppose that SAMPLE is another nametable 
similarly constructed. Then the expression 


NAMETABLEA .=QSAMPLE 


constructs an incidence map showing the points at 
which entries in the nametable correspond exactly 
to entries in the sample table. 


This is not the place to discuss the details of such 
applications, other than to point out that the ap- 
propriate choice of axes in establishing data arrays 
can make it possible to exploit powerful array 


Primitives in the APL language. 
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Chapter 9: 


ENTRY AND 
DISPLAY OF 
DATA ARRAYS 


ENTRY AND DISPLAY OF DATA ARRAYS 


The publication “Report Formatting in SHARP 
APL” describes in greater detail the functions that 
permit explicit control of the appearance of dis- 
plays, in particular those generated by the primi- 
tive functions 7 (thorn) and (FMT. See also the 
chapter of this manual entitled “Modes of Interac- 
tion at a Terminal.” 


Entering data 


A line (either a line of a defined function, or a 
line that you enter directly from the keyboard) 
may contain numeric or character data. When the 
actual value of the data (rather than the name of 
an array that contains the data) appears in a 
statement, that is said to be a constant. For exam- 
ple, the characters OK in the expression 
RESPONSE<'OK', or the numbers 1.05 and 1.09 
in the expression RATE+1.05 1.09 are constants. 
A constant consisting of a single number or a sin- 
gle character is a scalar. A constant containing 
more than one element is a vector. The elements 
of a numeric vector (but not of a character vector) 
are separated by blanks. 


There is no way to represent directly a constant 
whose rank is greater than 1. But it’s a simple 
matter to write an expression that forms the array 
you want from a scalar or vector constant. You 
form an array having more than one axis by ap- 
plying one of the reshaping functions to a vector 
or scalar constant. For example, a statement to 
create a 2-row matrix containing the characters 
RIGHT and WRONG might be: 


2 50'RIGHTWRONG' 


Representation of numbers 


Numbers that you enter from the terminal, or that 
the system displays, may appear in either of two 
forms: decimal or exponential. 


A number written in decimal form is constructed 
by use of the digits 0-9, and, if necessary, a 
decimal point and the negative sign `. It may con- 
tain at most one decimal point; if the point is not 
written, it is understood to be at the end. 


A number written in exponential form consists of 
a sequence of digits in decimal form, followed im- 
mediately by the letter F, followed immediately by 
digits representing an integer (without a decimal 
point). The integer following the F indicates a 
power of 10 by which the number preceding the 
E is to be multiplied. Thus, the number “one mil- 
lion” could be written as 1£6. 


A number whose value is negative is written with 
the symbol ` immediately to the left of the first 
digit. Watch out: this negative sign ` is not a 
function symbol, but part of the representation of 
a negative number. That means that you cannot 
use anywhere but as part of the representation 
of a numeric constant. In particular, the symbol 
~ may not be used next to the name of a variable; 
to get the values of an array named X with their 
signs reversed, you write -X but not X. 


A number written in exponential form may have 
a negative exponent. For example, the number 
“one millionth” could be written 1£ 6, while the 
number “negative one-and-a-half  millionths” 
could be written 1.5F 6. 


System displays in exponential form are nor- 
malized. That is, the digits are positioned so that 
the first high-order digit appears to the left of the 
decimal point and all others follow. But although 
the system normalizes the representation of num- 
bers it displays, you don’t have to normalize them 


when youre entering them. For example, 
6.02823, 60200F19, and .602F24 are equivalent 
entries, but the system would display each of them 
in the normalized form 6 .02F23. 


The only characters that may appear in the repre- 
sentation of a number are the digits 0-9, the high 
negative sign, the decimal point, and the letter £ 
used in exponential notation. No other characters 
are permitted. In particular, while you’re entering 
a numeric constant, you mustn’t put commas 
between triplets of digits; express “one million” as 
1000000 but not 1,000,000. That’s because the 
symbol , is used for the function “catenate.” 
However, displays produced by the formatting 
function [FMT may include commas or other arbi- 
trary characters. 


System-default displays 


Numeric output, or output generated by use of the 
monadic format function 7, is prepared according 
to the following rules: 


Significant digits: The number of significant 
digits in a display is controlled by the system vari- 
able OPP (for “print precision”). OPP must be an 
integer, and must be at least one and not more 
than eighteen; its value in a clear workspace is 10. 


Leading and trailing zeros: Neither leading 
zeros to the left of the units position, nor trailing 
zeros to the right of the units position, are dis- 
played. A leading zero in the units position is 
shown in displays, but you don’t have to write it 
while you’re entering. For example, the system 
writes 0.6 but you’re free to enter that as .6. 


Alignment of decimal point: In displays of ar- 
rays of rank 2 or higher, columns are displayed 
in fields of equal width, and decimal points are 
aligned. Perhaps it would be better to say that 
units positions are aligned, since integers are dis- 
played without a decimal point. For example, this 
matrix shows twelve numbers in steps of one- 
third: 


ENTRY AND DISPLAY OF DATA ARRAYS 52 


3 40(112)23 
0.3333333333 0.6666666667 1 
1.666666667 2 


3 3.333333333 3.666666667 4 


The set of printing positions that contain the char- 
acters used to represent a single column of num- 
bers is called a field. In a numeric display that 
is organized into columns (but not in a vector), 
the number of positions that can be used for non- 
blank characters is the same for every field 
throughout the display. The maximum number of 
non-blank positions is [PP+6. However, if the 
system can use narrower fields throughout the dis- 
play and still represent all the values, it does. 


In addition to the positions used for printed char- 
acters, every field other than the first has one extra 
position at the left which is always blank. The 
blank position is used to assure that a non-blank 
character from one field can’t appear right next 
to a non-blank character in a neighbouring field. 
However, no blank position is needed for the first 
field, and so its gross width is always one less than 
the gross width of the other fields. 


Choice of decimal or exponential form: In the 
case of a numeric vector, the system decides in- 
dependently for each element whether to display 
it in decimal form or in exponential form. Con- 
secutive elements of a vector are separated by one 
blank. Thus, 1 3 3.14159 6.0223 is a possi- 
ble display (or entry). 


When it’s displaying an array of rank 2 or greater, 
the system makes the decision to use decimal form 
or exponential form once for the entire array. 
Thus, such an array is displayed in the same form 
throughout: either entirely decimal, or entirely ex- 
ponential. Exponential form is selected when 
decimal display of the entire array would require 
a field to have more than DPP+6 non-blank posi- 
tions. 


Number of lines used to display an array: An 
array having a rank greater than 2 is displayed 
as a succession of matrices. Successive positions on 
the 3rd-from-last axis are separated by one addi- 
tional blank line, successive positions on the 4th- 
from-last axis by 2 blank lines, and so on. 
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1.333333333 
2.333333333 2.666666667 


The number of printed lines required to print an 
array X (excluding the extra blank lines used to 
separate planes, etc.) is given by x/ 14pX. Note 
the following consequence of that formula: an 
empty vector is printed as a single blank line, but 
an empty array of any rank other than 1 is not 
printed at all. An array having rank 2 or more but 
no columns is not printed at all, either. 


There exist fractions that can’t be represented 
precisely: There are some fractions which can’t 
be represented precisely in any number system 
based on integers. Perhaps more vexing in com- 
puting is the fact that certain fractions which can 
be represented precisely in the decimal system 
nevertheless cannot be represented precisely in the 
base-16 arithmetic used internally by the computer 
which is used to run SHARP APL—and vice 
versa. Each time you enter a fraction from the 
keyboard, the system converts that to the best base- 
16 representation. Each time you display a result, 
it converts back from base 16 to base 10. It is 
possible that after the two conversions, the 
system’s display is no longer identical to the value 
you entered. That’s especially likely if you are 
using the system’s maximum print precision (18 
decimal digits). In choosing a decimal form for a 
hexadecimal value that has no exact decimal 
equivalent, the system favours the shorter decimal 
forms. This may occasionally mean that if you 
enter a very long decimal fraction, the system will 
display a truncated (but close) form. Thus, when 
OPP+18, if you enter .07000000000000001, the 
system displays that as 0.07. 


Characters in the APL language, in the APL 
system, and at the terminal 


Characters in the APL language, characters in the 
APL system, and characters at an APL terminal, 
are three categories which, while related, are dis- 
tinct. It’s important to distinguish them. 


Abstract characters in the APL language: The 
APL language provides for 141 characters. These 
are the characters that might appear in a printed 
publication written in APL. They are evoked on 
paper by forming certain marks, or at an APL 
system by pressing certain keys on the terminal, 
or by referring to certain elements in an APL data 
array. 


Character data: Within a workspace, there are 
256 distinct values which may appear in a charac- 
ter array. Notice that there are considerably more 
possible character values than there are characters 
recognized in the APL language. For some of 
those possible character values, there’s no way at 
all to enter them from the keyboard, and no way 
they can be displayed at a terminal. 


A reference vector containing each of the 256 pos- 
sible characters is generated by the niladic system 
function DAV (for “atomic vector”). The elements 
produced by [JAY are generated in ascending order 
of the number obtained by treating the bit-pattern 
assigned to each character as a binary number. 
Thus, the first element of DAV is the character 
whose internal representation is 0, and the last is 
the character whose internal representation is the 
number 255 (hexadecimal FF). The reference set, 
generated by DAV, can be used to interpret charac- 
ter data received from sources outside the APL 
system, or to generate data encodings intended for 
use outside the APL system. 


Each of the 141 possible APL characters is as- 
signed a position in [JAV. In that sense, the set of 
recognized APL characters is a subset of DAV. But 
note that different APL systems make this assign- 
ment differently; it is imprudent to write an ap- 
plication that generates a display or an executable 
statement by direct reference to QAV, especially if 
there is even a remote possibility that it will be 
executed in other APL systems. 


Terminal transmission codes: When a charac- 
ter is entered from a terminal, or sent to a termin- 
al for display, a sequence of bits is transmitted 
between them. The transmission code is not the 
same as the bit-pattern used internally to store a 
character; indeed, to transmit an image of a single 
APL character may require several transmitted 
characters. 


Transmission codes are ultimately determined by 
the terminal manufacturer, who builds into the 
terminal a mapping from keys to transmission 
codes, and from transmission codes to displays or 
other actions. The SHARP APL system translates 
from APL characters to one of four commonly 
used encoding schemes for transmission codes. 
These are two ASCII encoding schemes, for bit- 
pairing and typewriter-pairing devices, and two 
different systems used in IBM terminals (BCD 
encoding, and “correspondence” encoding). These 
encodings are normally invisible to the user. The 
system decides which should be employed by 
analyzing your sign-on transmission and deducing 
the encoding your terminal is probably using. You 
could make certain adjustments to the timing of 
transmissions in order to best match characteristics 
of certain terminals by using the command 
)TERM. 


Entry or display of unrecognized characters 


The transmission control of the APL system trans- 
lates APL characters to transmission codes and 
vice versa. However, the mapping that permits this 
translation is not complete. Certain elements of 
DAV have no distinct transmission code. If you 
attempt to send such a character to a terminal, the 
system represents it by codes that display a charac- 
ter not otherwise permissible in input or output, 
to mark the position at which an undisplayable 
character is located. At present, the character used 
for that purpose is J] (“‘squish-quad”). That is not 
an APL character, but a convention used by the 
APL system to indicate a character for which there 
is no assigned graphic. 


Similarly, many terminals are capable of transmit- 
ting to the APL system codes to which the APL 
system attaches no significance. This is especially 
likely if you use BACKSPACE to construct over- 
strikes other than the handful of recognized APL 
characters that can be formed in that way, or if, 
at an ASCII terminal, you transmit to the APL 
system, codes generated with the ESCAPE or 
CONTROL keys. Certain devices not primarily in 
tended for use as APL terminals may unavoidably 
transmit codes uninterpretable to the APL system; 
to minimize this problem, the system receives but 
ignores ASCII “escape” and ASCII control codes. 


ENTRY AND DISPLAY OF DATA ARRAYS 54 


When the system’s input processor receives a 
transmission containing an uninterpretable over- 
strike, it rejects it with the message CHAR 
ERROR. Then it prompts you by displaying the 
line up to the first uninterpretable character. 
(That message may also on occasion be triggered 
by noise in the communication link, causing the 
system to receive a garbled and hence uninterpret- 
able code.) 


Explicit control of transmission codes 


The system functions JARBOUT and DARBIN per- 
mit you to generate transmission codes directly, or 
to receive directly the transmission codes sent from 
a terminal. The argument of [JARBOUT is com- 
posed of numbers (or of characters from [JAV to 
represent numbers in the range 0-255). The result 
is numeric. It is then up to you to decide what 
significance you attach to those numbers. Sending 
and receiving arbitrary transmission codes is dis- 
cussed further in the chapter on modes of interac- 
tion at a terminal. 


Characters with special significance at the ter- 
minal 


There are six keys at the terminal which directly 
affect the interpretation of the line transmitted, but 
which never themselves generate a character that 
becomes part of the input line. These are RE- 
TURN, BACKSPACE, LINEFEED, TAB, and 
ATTN or BREAK, and the SHIFT transmitted 
by the IBM 2741 terminals. 


RETURN marks the end of the transmission from 
a terminal, but does not become part of the input 
line (except when you’re using [JARBIN). 


BACKSPACE is used to re-position the cursor in 
order to make an overstrike or to select a point at 
which the input line can be corrected. 


LINEFEED is used to mark the point at which 
the line now being constructed is to be corrected. 
Characters appearing above and to the right of it 
are ignored, while those to the left of it are re- 
tained. 
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TAB is converted by the system to an appropriate 
number of blanks. The system can interpret the 
significance of your use of the TAB key only if 
the positions at which tab stops are set on the 
terminal have previously been specified. You do 
that by supplying a value for the system variable 
DHT (for “horizontal tabs”). Pressing the TAB 
key when DHT has no valid setting, or when the 
cursor is to the right of the rightmost value des- 
cribed in DHT, is rejected as a CHAR ERROR. 


SHIFT on most terminals is a key local to the 
terminal. It alters the effect of pressing the other 
keys on the keyboard, but doesn’t itself transmit 
anything to the computer. The IBM 2741 does 
transmit when SHIFT is pressed, but the system’s 
transmission control unit treats it as a signal that 
governs how the following signals should be inter- 
preted, and not as a separate character. 


ATTN or BREAK is used to interrupt execution 
or display. In addition, on IBM terminals, ATTN 
may be used during input to mark the point at 
which a correction is to be made, in the same way 
as LINEFEED. During execution, the system dis- 
tinguishes two levels of urgency. A single use of 
ATTN or BREAK is called an “attention”. It 
causes the system to halt when it finishes execution 
of the line it is currently working on. Two con- 
secutive uses of ATTN or BREAK is called an 
“interrupt”. It causes the system to halt work 
without waiting for completion of the current line. 
(In the IBM manual APL Language, these are 
called “weak interrupt” and “strong interrupt,” 
respectively. ) 


The sequence 0 BACKSPACE U BACKSPACE 
T does not produce a character, but serves to inter- 
rupt input in the same way that interrupt does 
during execution. (The sequence 0 BACKSPACE 
U BACKSPACE 7 is sometimes called an “escape 
sequence,” but don’t confuse it with the key label- 
led ESCAPE that is present on some ASCII ter- 
minals. The ASCII ESCAPE key is used for set- 
ting various controls within the terminal, and 
emits a signal that the APL system ignores, except 
when you’re using JARBIN.) 


Characters that can be displayed but not en- 
tered 


There are six characters that may exist within a 
character array and may be transmitted to a ter- 
minal for display, even though there is no way you 
can enter them from the keyboard directly. These 
are carriage return, backspace, linefeed, idle, and 
null, plus a character having specific significance 
only for the IBM 2741: upper-case backspace. 
Since there’s no way you can enter these directly, 
the workspace 1 WSFNS contains those characters 
as variables. When you need one of them, you can 
copy it from that workspace. The variables and 
their significance are as follows: 


CR Carriage return: Displaying an array 
containing this character causes the charac- 
ter following it to appear at the left margin 
on the following line. 


Note: ASCII terminals distinguish between 
the act of returning the cursor to the left 
margin and the act of moving the cursor to 
the line below, whereas IBM terminals use 
a single character to mean the two actions 
together. Regardless of the type of terminal 
you’re using, CR causes the next character 
to appear at the left margin on the line 
below. To achieve that, to an ASCII termin- 
al the system transmits the codes necessary 
both to return the cursor to the left and to 
move it one position down. 


BS Backspace: Causes the next character dis- 
played to appear at the same position as the 
preceding character. 


At a typewriter-like terminal, this produces 
an overstrike. At a CRT (cathode-ray tube) 
terminal, it may or may not produce an 
overstrike, depending on features of the par- 
ticular terminal. 


LF  Linefeed: This character moves the cursor 
one line down, but neither returns it to the 
left margin nor advances it to the right. 
Thus, the sequence 

"FIRST! ,LF,'SECOND' 
is displayed as: 


FIRST 
SECOND 


ID Idle: This character is transmitted to the 
terminal (and takes the same length of time 
to transmit as any other character) but the 
terminal does nothing with it. You might 
use it to produce a hesitation in the display 
of a sequence of characters transmitted 
together. When you’re using a typewriter- 
like terminal, the system automatically 
transmits idles to allow time for the reposi- 
tioning of the paper or the typehead follow- 
ing a carriage return or linefeed. 


NUL Null: The system does not transmit any- 
thing, but proceeds immediately to transmis- 
sion of the next character. 


UBS Upper-case backspace: IBM 2741 and 
similar terminals distinguish between 
upper-case and lower-case backspace. At 
such a terminal, BS requires the terminal to 
shift to lower-case (if it isn’t already in 
lower-case) before backspacing. Thus, UBS 
is executed more quickly if the characters 
before and after it are both in upper-case. 


This distinction is meaningless at an ASCII 
terminal, and there BS and UBS are 
equivalent. 


Control characters ignored 


Certain characters used for local control of a ter- 
minal (for example, ESCAPE at an ASCII ter- 
minal) are ignored during any input except input 
in response to [ARBIN. The terminal, of course, 
responds to them as usual, but—unless you are 
using arbitrary input with [JARBIN—the APL 
system acts as though they had not been transmit- 
ted to it. 


APL character set 


The following list includes all characters that may 
appear in a function definition or in a line to be 
executed. Each of them may be evoked by an entry 
from the keyboard, or transmitted to an APL ter- 
minal for display. This set of “enterable” charac- 
ters corresponds exactly to the set of abstract char- 
acters in the APL language. 
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Because some terminals don’t have a key 
specifically for certain characters, you evoke those 
characters by overstriking one character with 
another; a character you evoke that way is still a 
single character. Where a character may be formed 
by overstriking, the characters to be overstruck are 
shown in the chart to the right of the single char- 
acter. The order in which keys are struck to 
produce an overstrike is not significant. 


(The system also tolerates certain overstrikes 
which, at a typewriter with APL font, superim- 
pose neatly. For example, it accepts: 


F overstruck with EF as E 
: overstruck with ; as ; 
. overstruck with , as , and so on.) 











Alphabetic characters 
p 
A 
A 
Numerals 
01234567839 


Other characters 
ee 





e + 





57 ENTRY AND DISPLAY OF DATA ARRAYS 


LIST OF ENTERABLE CHARACTERS 


Dieresis 


A single character may be referred to by any of 
several names. There may be a name for the char- 
acter itself, or one or more names derived from its 
use. Since most symbols may serve both for a mon- 
adic and for a dyadic function, the name may 
differ according to the context. A name dependent 
on use is marked F1 for function of 1 argument; 
F2 for function of 2 arguments; and Op for use 
as an operator. Note that the characters 

coəonuaw _8¢ {}F are con- 
sidered part of the APL character set even though 
at present they have no assigned use in the APL 
language. 









Overbar; negative; high minus 
< Less than 
< Less than or equal; not greater 
= Equal 
2 Greater than or equal; not less 
> Greater than 
z Not equal 
v Inverted caret; F2: or 
A Caret; F2: and 
x v~ Nor 
n A~ Nand 
a Hyphen; F1: negative; F2: minus 
F1: conjugate; F2: plus 


F1: reciprocal; F2: divide 
F1: signum; F2: times 
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Domino; F1: matrix inverse; F2: matrix divide 
Dollar 

Diamond 

Query; random; F1: roll; F2: deal 
Omega 

Epsilon; F2: set membership; “is a member of” 
Rho; F1: shape; F2: reshape 

Tilde; F1: not 

Up arrow; F2: take 

Down arrow; F2: drop 

Iota; F1: index generator; F2: index of 
Circle; F1: pi times; F2: circular 
Circle-stile; F1: reverse; F2: rotate 
Circle-bar; F1: 1st-axis reverse; F2: 1st-axis rotate 
Transpose 

Log 

Star; exponentiation 

Right arrow; F1: branch to 

Left arrow; F2: specify; assign 

Right tack 

Left tack 

Alpha 

Up-stile; F1: ceiling; F2: max 
Down-stile; F1: floor; F2: min 
Underbar 

Del 

Del-tilde; function lock 

Upgrade 

Downgrade 

Null; jot 

Quote 

Shriek; F1: factorial; F2: combinations; binomial 
Quad 

Quote quad 

Left parenthesis 

Left bracket 

Right parenthesis 

Right bracket 

Right brace 

Left brace 

Left shoe 

Cent 

Right shoe 

Cap 


Lamp; comment 


z 
w 
€ 
p 
t 
4 
1 
O 
> 
i] 
X 
® 
* 
> 
< 
4 
= 
a 
j 
L 


POUANAwuUWYSY nmnaBO.-- - oo 4e dal 
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LIST OF ENTERABLE CHARACTERS 


Cup 

Base; F2: decode; base value 

Hydrant; F1: execute 

I-beam 

Top; F2: representation; encode 

Thorn; character representation; format 

Stile; F1: absolute value; F2: residue; modulus 
Semicolon 

Colon 

Slope; back slash; F2: expand; Op: scan 
Slope-bar; F2: 1st-axis expand; Op: 1st-axis scan 
Comma; F1: ravel; F2: catenate; laminate 

Dot; period; decimal point; Op: product 

Slash; F2: compress; Op: reduce 

Slash-bar; F2: 1st-axis compress; Op: 1st-axis reduce 
Blank; space 


Zee — A dHeeE SC 


Internal representation of characters 

a 

The table shows the position in DAV of each of the 141 enterable characters. The positions are 
shown in 0-origin, with the hexadecimal representation in parentheses beside the decimal repre- 
sentation. 


Enterable 


(04) 
(05) 
(OF) 
(OF) 
(10) 
(11) 
(12) 3 
(13) 
(14) 
(15) 
(16) 
(19) ` 


e€vovemMeKV WV I 


X 


AA <> emn eK I + 


© 
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62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
77 
78 
79 
80 
81 
82 
83 
86 
87 


ODBIDHFWNROPINK)S< 


Je 


WenawrTloramrnrnOasernereGoOorHese 
NSN TENSCHHBDO VOSS HRY RD YAOO 
NIG hh D N10 Se IPS IS TAY RID Ry I I 1 lo ha > 


Not enterable 


(00) Idle 

(01) Null 

(9C) Carriage return (i.e. new line) 
(9E) Backspace 

(9F) Linefeed 

(42) Upper-case backspace 
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Chapter 10: 


MODES OF 
INTERACTION 
AT A TERMINAL 





The system may treat the entries you make from 
a terminal in any of several different ways. These 
are called modes of entry. 


The fundamental mode in which the system oper- 
ates is called immediate execution mode. That’s 
the mode the system is normally in when you first 
sign on, and it’s the mode to which the system 
returns when it halts execution of a program. 
Each of the other modes is a temporary departure, 
during which a line that you enter from the key- 
board is treated differently. 


SHARP APL provides the following modes: 


1. Immediate execution: As soon as you finish 
entering the line (that is, when you press the RE- 
TURN key), the system executes it. 


1a. Line editing: The system displays the 
preceding immediate-execution APL entry, and 
waits for you to indicate how it should be correct- 
ed. Following correction, the line becomes your 
next entry. 


2. Function definition: You may enter, display, 
or edit the definition of a function. 


2a. Line editing within function definition: 
You may edit a line of the function whose defini- 
tion is now open in the same manner as line edit- 
ing of the last-entered execution line. 


3. Data input: A statement being executed re- 
quests one line of input from the keyboard. Data 
input has three forms: 


3a. Character input: The next line you 
enter is treated as character data, and passed to 
the statement that evoked character input mode. 


3b. Evaluated input: The next APL line 
you enter is evaluated, and the resulting value is 
passed to the statement that evoked evaluated 
input. 
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3c. Arbitrary input: An exact record of the 
transmission (for example, the sequence of key- 
strokes) from your terminal is passed to the state- 
ment that evoked arbitrary input. 


Of those three modes, immediate execution and 
function definition, once entered, remain in effect 
until what you enter causes a switch in mode. The 
various forms of data input, and the line editing 
mode, each apply only to the next entry. 


A mode can be characterized by the following 
things: 


1. How you get into it. That is, what you have 
to do to signal the system that it should enter a 
particular mode. 


2. How you know you’re in it. The system be- 
haves differently to mark what mode it’s in. That 
makes it easier for you to tell how the system will 
interpret your entry, or for you to identify what 
mode you’re in now so you can switch to some 
other mode. 


3. What you can do while in it. 


4. How you switch to another mode. 


Immediate execution mode 


Immediate execution mode is the system’s default 
mode of operation. There is no specific signal that 
means “Start immediate execution.” Rather, the 
System returns to immediate execution mode au- 
tomatically: 


1. When you sign on, unless at sign-on the system 
automatically loads the workspace CONTINUE and 
the workspace CONTINUE contains a latent expres- 
sion which, when executed, puts you into some 
other mode. The workspace CONTINUE is automat- 
ically loaded at the start of a session if you ended 
your previous session by the command 
)CONTINUE, or if your previous session ended 
without a normal sign-off (for example, as the 
result of a line drop, a system crash, or a 
“bounce” ). 


2. Following the command )CLEAR, and following 
any system command entered while in execution 
mode. However, following successful execution of 
a )LOAD command, the system immediately exe- 
cutes the expression contained in the visible value 
of the system variable OLX (latent expression), 
and that may in turn invoke one of the data-entry 
modes. 


3. When the system finishes executing a line you 
entered from the keyboard during execution mode. 


4. When the system encounters an error or an 
interrupt signal during execution of a program. 


5. When you load a workspace, unless the work- 
space contains a latent expression which, when 
executed, puts the system into some other mode. 


Execution mode is marked by a six-space in- 
dentation: That is, before turning the keyboard 
over to you for entry, when the system is in execu- 
tion mode, it always moves the cursor to the 
seventh position from the left margin. This isn’t 
a foolproof indicator, since it is possible to write 
a program that moves the cursor to the same posi- 
tion before awaiting character input or arbitrary 
input. But if the system doesn’t move the cursor 
to the seventh position, you can safely conclude 
that you aren’t in execution mode. 


While the system is in immediate execution mode, 
you can: 


1. Enter any line of APL for immediate execu- 
tion (including one that will, in turn, invoke one 
line of evaluated input, character input, or arbi- 
trary input). 


2. Enter any system command. An entry whose 
first non-blank character is ) is treated as a system 
command. 


3. Switch to line editing mode, by entering ) 
alone, or ) followed solely by a number. 


4. Switch to function definition mode, by enter- 
ing a line whose first non-blank character is V, 
followed by the name of an existing function, or 
the header of a new function. 
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While you’re in immediate execution mode, the 
system makes the following assumptions about the 
line you enter: 


1. Any entry whose first non-blank character is 
) is a system command. 


2. An entry whose first non-blank character is V 
is a request to enter definition mode. 


3. Any entry that isn’t either of the first two is 
a line of APL for immediate execution. This 
means that any name (unless it’s in quotes or part 
of a comment) is treated as the name of an APL 
object. 


Function definition mode 


Function definition mode is one way of creating, 
displaying, or editing the definition of a function. 
It isn’t the only way; you can do the same or 
similar things with the system functions OCR, 


OFX, and DFD. 


Enter definition mode from immediate execu- 
tion mode: The signal to switch to definition 
mode is an entry that starts with the character 
y. You remain in that mode until you enter a line 
that ends with V or ¥. The opening V means that 
you want to start definition mode, and the closing 
y means that you want to leave it. Using ¥ instead 
of V to close a definition causes the function’s defi- 
nition thereafter to be locked. That is, it can never 
again be displayed or edited. 


Definition mode with respect to only one func- 
tion at a time: When you enter definition mode, 
it’s with respect to the definition of one function. 
The only way to edit another function is to leave 
definition mode, and then re-enter definition mode 
with respect to the other function. 


Once you enter definition mode, each entry is 
taken as part of the definition of a function that 
you are supplying, or else a request to display or 
modify the definition. Note that while you are in 
this mode, entering an APL line causes it to 
become part of the definition of a function. The 
line is not executed; it isn’t checked for validity 
(unless it’s the header line, which is checked for 
correctness). 


Function editing with V always refers only to glob- 
al objects. You can’t use it to enter, display, or edit 
a local function. Using V, it is possible to edit 
the definition of a function that has been sus- 
pended, and then, after revising its definition, re- 
suming its execution. But this can be done only 
if the function is represented in the state indicator 
on the top row (the most recently invoked func- 
tion), and nowhere else. 


Entering definition mode to create a new func- 
tion: When you are entering definition mode in 
order to create the definition of a new function, 
to the right of V write the entire header of the 
new function. The name you are giving the func- 
tion must be a name that isn’t now in use as the 
name of a group, or of a global variable or func- 
tion. 


Entering definition mode to edit or display an 
existing function: When you want to enter 
definition mode with respect to a function that 
already exists in the workspace (to display it, or 
to alter its definition), following the opening del 
you write only the name of the function, without 
mentioning the header. 


Bracketed line numbers mark definition mode: 
Definition mode is marked in the following way. 
Before turning the keyboard over to you for your 
entry, the system displays a line number in brack- 
ets. The line number it shows is the number next 
after the line you just entered or edited. If this is 
a new definition, it’s the line numbered [1]. If 
you're just re-opening the definition of an existing 
function, it’s one more than the last line already 
entered. Otherwise, the system computes the 
“next” line number by adding the digit 1 in the 
last place; that is, after [9] it proposes [10]; 
after [3.02] it proposes [3.03]. 


Options once the system prompts you with a 
line number: To the right of the line number 
that the system supplies, you can write any of the 
following: 


1. An APL line: What you write becomes that 
line of the function’s definition. 
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2. Another line number in brackets: That 
may or may not be followed by an APL line. The 
substitute line number overrides the line number 
supplied by the system. If you provide a fractional 
line number, it is interpolated between existing 
lines. For example, line [3.2] goes after line 
[3] and before line [4]. The APL line you write 
following the line number is entered as part of the 
function’s definition. If you don’t include a line, 
the system prompts you for one. 


3. A request to display the entire definition: 
You do that by entering [0]. 


4. A request to display the entire definition 
starting from a given line number: You do 
that by entering [On], where n is the number of 
the line at which you want display to start. 


5. A request to display a particular line: You 
do that by entering [n0], where n is the number 
of the line you want displayed. Following the dis- 
play, the system prompts you with the same line 
number, so that you may, if you wish, enter a 
substitute definition for that line. 


6. A request for line editing of a single line: 
You do that by entering [n0x], where n is the 
number of the line you want to edit, and x indi- 
cates where in the line you want the cursor posi- 
tioned. This is a special mode within function edit- 
ing, and is described in the section entitled “Line 
Editing in Immediate Execution and in Function 
Definition Modes.” 


7. A request to capture the preceding APL 
line: You can capture the last line entered for 
immediate execution (before you entered definition 
mode) by entering ) alone, or ) followed solely 
by a number. That causes the system to display 
the preceding APL line, and permits you to edit 
it (if you want) as described under “Line Editing 
in Immediate Execution and in Function Defini- 
tion Modes.” When you have completed editing it, 
the line becomes a line of the definition of the 
function you’re now editing. 


8. A request to delete a line: You do that by 
entering, within brackets, the symbol A, followed 
by the number of the line or lines you wish to 
delete. 


(SHARP APL continues to tolerate an older 
method of line-deletion, now considered obsolete. 
That method required going through the cycle 
usually used at the terminal you’re using to mark 
an erasure in the line currently being entered. At 
an ASCII terminal, that consisted of pressing 
LINEFEED and then RETURN. At an IBM- 
coded terminal, you could also use the sequence 
ATTN RETURN.) 


To leave definition mode: Write the character 
V or Ẹ as the last non-blank character of an entry 
(but not part of a comment). The V or ¥ may 
stand alone, or may simply appear to the right of 
a line you’re entering, provided the line doesn’t 
contain a comment. It doesn’t matter what line you 
were entering when you write the closing V; the 
closing V means you want to leave definition mode, 
but it doesn’t mean that the line on’ which you 
enter it is the last line of the function. 


Line editing in immediate execution and in 
function definition modes 


The system provides a built-in mechanism to edit 
and re-execute your last APL entry—with or 
without display. You can use the same mechanism 
to edit a line of a defined function. Because it’s 
a built-in facility, it’s always available, and doesn’t 
require a particular program or workspace. 


Correcting a line before you’ve pressed RE- 
TURN: Before you’ve pressed RETURN, the 
LINEFEED key deletes the character at the pre- 
sent cursor position and everything to the right of 
it. (Position the cursor with SPACE or BACK- 
SPACE.) 


While you're entering a line of APL from the 
keyboard, and before you’ve pressed the RE- 
TURN key to request the system to act on it, you 
may notice you’ve made a typographical error. 
You can correct that mistake by backspacing until 
the cursor is at the error. Pressing the LINE- 
FEED key (ATTN on IBM terminals) deletes 
the unwanted character as well as everything 
typed to the right of it. 
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definition mode. 





The diagram below illustrates the options available in both immediate-execution mode and in function- 
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M EXECUTES THE AMENDED LINE 


Immediate Execution: SYSTE 
Function Definition: SYSTEM KEEPS THE AMENDED LINE 








The cursor moves down one line, so that it is 
directly below the point from which you erased. 
Then you can retype the balance of the line. Use 
LINEFEED (or ATTN) again, as often as you 
need, to make further changes. The system doesn’t 
attempt to evaluate your line until you press RE- 
TURN. 


Z+'THE TOTALIS: '(4 BS) LF 
@IS: 'RETURN 
@ 


The example above illustrates what you see at the 
terminal when you use the BACKSPACE LINE- 
FEED (BS LF) combination. The @ character 
indicates the position of the cursor. 


Editing after you’ve pressed RETURN: You 
can bring back a line that’s already entered and 
edit it. There are two situations in which you can 
do that: 


1. While you’re in immediate execution mode, 
recall a line by entering ) either alone or followed 


65 MODES OF INTERACTION AT A TERMINAL 


by a number. That lets you edit the one preceding 
line of APL entered from the keyboard in immedi- 
ate execution mode. 


2. While you’re in function definition mode, re- 
call a line of the function’s definition by entering 
[mOn], where m is the number of the line. The 
number that follows the [] serves the same purpose 
as the number that follows the ) while you’re in 
execution mode. 


When you’ve finished editing the line, the system 
executes it (if you’re in execution mode) or makes 
it part of the function’s definition (if you're in 
definition mode). 


Note that you cannot bring back a line of entry 
which started with a ) or a V. This means that 
system commands and entries requesting function 
definition cannot be recalled. 


One-pass editing 


) or )O requests one-pass editing of the previous 
APL line. [m00] requests one-pass editing of line 
m. The system displays the line and leaves the 
cursor at the end of it. 


After the system displays the line, it turns the 
keyboard over to you and waits for you to modify 
the line. When you’ve entered your changes and 
again press RETURN, the system acts on the line, 
including your alterations. 


The request [m00] or )0 leaves the cursor wait- 
ing on the same line at the next available position 
to the right. A right parenthesis standing alone has 
the same effect as )0. 


Writing some more on the same line: Suppose 
the change that you want to make is an addition 
to the end of the line. The quickest way to do this 
is to request editing with )O or [m00]. The 
system displays the line and leaves the cursor on 
the same line, in the next available position to the 
right. 


)O 
| Z<'THE TOTAL IS: '@ 


~_~ 


The system now awaits additional characters on 
the same line. When you’ve typed the additions, 
pressing RETURN causes the system to act upon 
your revised line without further display. 


Z«'THE TOTAL IS: 
@ 


''ZIP''*RETURN 


Two-pass editing 


Positioning the cursor: )n requests two-pass 
editing of the last APL line. [mOn] requests two- 
pass editing of line m. The system displays your 
line and puts the cursor on the following line at 
the position designated by n. 


After [mOn] or )n causes display of the line 
you've requested, the system waits with the cursor 
on the following line at the position you indicated. 
You can use any positive integer as long as it is 
not greater than the value of the system variable 
OPW (Page Width). 


You don’t have to calculate n exactly; you can 
always use SPACE, BACKSPACE, or TAB to 
adjust the position of the cursor. 


Deletions: During two-pass editing, each char- 
acter marked with a slash is deleted. (However, 
all characters are treated as text when they are to 
the right of a dot or a comma.) 


After you request two-pass editing with [mOn] or 
)m, enter a / under each character to be deleted. 


)17 
Z«'THE TOTAL IS: ''ZIp'': 


/RETURN 


After you press RETURN, the system displays 
the line with the deletions. The cursor waits on 
the same line at the next position to the right. 


Z-'THE TOTAL IS:''"ZIP'''@ 


If after you’ve made deletions, you wish to add 
additional characters to the right of the line, you 
can enter them directly. Pressing the RETURN 
key tells the system to take the line, as it appears 
at the terminal—that is, after your deletions and 
additions. 
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Coal 


ad 


Notice that you can delete any number of charac- 
ters. The deleted characters don’t have to be con- 
secutive. However, the slash marks that indicate 
deletion must be to the left of a dot or comma (if 


any). 


)24 
Ze'THE TOTAL IS: ''ZIP''' 
/////RETURN 
Z«'THE TOTAL IS: ''Z@ 


You can append one or more characters to the 
right of the line. 


Z<'THE TOTAL IS: ''ZERO'' ‘RETURN 


@ 
Z 
THE TOTAL IS: 'ZERO' 
@ 
Insertions: There are two ways to do insertions: 


1. First insert enough blanks to accommodate the 
insertions. The blanks don’t have to be consecu- 
tive. In another pass, overstrike the inserted blanks 
with the characters you want. 


2. Insert a single block of consecutive text. 


Watch out: Don’t insert so many blanks that the 
line would be more than [PW positions long. See 
“Common Errors” for details. 


Blanks that the system uses to position the cursor 
(for example, the 32 blanks you’d get if you enter 
two-pass editing with )32) do count as characters. 
If you ask for a position that’s this far to the right, 
and then backspace, the blanks are still part of the 
line unless you explicitly erase them. 


Scattered insertions: To the left of each position 
that you mark by an alphanumeric character 0-9 
or A-Z the system inserts blanks. (However, all 
characters are treated as text when they are to the 
right of a dot or a comma.) The digits one to nine 
insert the corresponding number of blanks. The 


} Z-'THE TOTAL IS:@ 


~*~ 


letters A to Z insert blanks according to the code: 
A equals five, B equals ten, C equals fifteen, ete. 


)17 
Z+'THE TOTAL IS: ''ZERO''' 
@ 
2RETURN 
't7RROI! 


The system displays the line with two blanks in- 
serted. The cursor is on the same line waiting at 
the leftmost of the blanks you inserted. The key- 
board is turned over to you. You may then over- 
strike the blanks with the characters you want to 
insert. (In the example above, the 2 is on the 
following line for illustrative purposes only.) 
When you press RETURN, the system acts on the 
line as modified. 


Ze'THE TOTAL IS:***''ZERO'! ‘RETURN 
@ 


Block insertions: If the line you enter contains 
a dot or a comma, any characters to the right of 
the first dot or comma are a block of text to be 
inserted. There are two ways to do this: 


Terse editing (marked by . ) 
Serial editing (marked by , ) 


The presence of a dot or a comma divides your 
editing entry into three fields: 


1. To the left of the first dot or comma (or the 
whole line, if there isn’t any dot or comma), scat- 
tered deletions and insertion of blanks. 


2, The dot or comma indicates where a block in- 
sertion is to go, and where you want the cursor 
to be afterwards. 


3. To the right of the first dot or comma, all 


characters are text to be inserted as a consecutive 
block. 


Terse editing 


If you want to edit in one pass and without dis- 
play, use the dot form of editing. The system acts 
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on the revised statement immediately, as soon as 
you press RETURN. Entering a dot alone after 
you’ve requested line editing causes the system to 
act on the line immediately. 


Example of insertion using . 


)26 
Z*'THE TOTAL IS:**x'*'*ZERO'' 
. 'RETURN 


The system makes the insertion you requested and 
acts on the revised statement without displaying 
it. (In this example, you could verify that your 
insertion was accepted by asking the system to 
display the altered value of the variable Z.) 


Z 
THE TOTAL IS:*xxx'ZERO!' 


You may insert any characters (including blanks), 
punctuation, and APL symbols (including those 
formed by overstriking one character with anoth- 
er). Note that blank is a character. (You can’t see 
it, but it is.) BACKSPACE is not a character. It 
serves only to position the cursor. To insert a dot 
with the dot form of editing, you will need two 
dots. The first dot locates the character which you 
want to appear immediately to the right of the dot 
you insert. 


Example of simultaneous deletions and inser- 
tion 


With the dot form of editing, a combination of 
slashes, alphanumerics, and a block of text to the 
right of the dot causes the simultaneous deletion 
and insertion of characters. Pressing RETURN 
tells the system to act on the revised line without 
display. 


Using / and . together, you can combine an inser- 
tion and several deletions. (However, the deletions 
have to be to the left of the insertion.) Each slash 
you enter to the left of the first dot indicates a 
character to be deleted. All characters which you 
enter to the right of the first dot are to be inserted. 


Put the dot where you want the inserted characters 
to go. The character above the dot will follow the 
insertion. 


)4 
Ze'THE TOTAL IS:***""ZEROt it 
//// // //....RETURN 
@ 


The system accepts the simultaneous deletions and 
insertion, and immediately acts on the modified 
line without displaying it. Note that you can 
insert dots in your line. Anything after the first 
dot or comma gets inserted. 


Z 
TOTAL IS:***ZERO!... 


Serial editing 


If you want to edit in successive passes with dis- 
play, use the comma form of editing. The system 
displays your line—with current revisions—and 
waits for you to make further alterations. When 
you've finished making changes, entering a dot and 
pressing RETURN tells the system to act upon 
the line without further display. 


Successive alterations: Comma editing follows 
the same convention as dot editing. That is, to the 
left of the first comma, each slash or alphanumeric 
character deletes or inserts blanks. The block of 
characters to the right of the first comma is text 
to be inserted. The comma locates the character 
or blank which you want to appear immediately 
to the right of the added characters. (That is, you 
want your insertion to appear to the left of the 
character under which you type the comma.) 


When the system has made the deletions and the 
insertion, it displays the line as it now appears, 
and awaits further instructions. The new instruc- 
tion may contain a dot, a comma, or neither. 


)12 
Ze'TOTAL IS:**x*ZERO!...! 
/, 
Z«'TOTAL ISx**xZERO!...! 
@ 
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Notice that the cursor appears on the following 
line under the character where you initially en- 
tered the comma. The keyboard is turned over to 
you and you can now make further changes ac- 
cording to any of the conventions allowed during 
two-pass editing. (The insertion in the example 
below is shown on the following line for illustra- 
tive purposes only.) 


Z+-'TOTAL IS***ZERO!...' 
//11111//1/1, (0)RETURN 
2«'TOTAL IS (0)' 
@(13 BS) 
_THERETURN 


Re-invoking line editing: Once you've used a 
dot, the system acts on the line. If it turns out that 
your modified line still isn’t satisfactory, you can 
always invoke line editing again. For example, the 
preceding sample showed a dot used to insert 
THE. In fact, that wasn’t correct. If you display 
Z you'd see 


Z 
THETOTAL IS (0) 


















SUMMARY OF LINE EDITING 


Command Description 


LF Before pressing RETURN, LINEFEED deletes charac- 
ters above and to the right of the cursor. Position the 
cursor with SPACE or BACKSPACE. 


You could make a new correction by invoking )4 
and using a dot followed by one blank. ‘The system 
would make the change, but since you used dot 
rather than comma, wouldn’t show it to you. 


Changing your mind—aborting editing: The 
consecutive keystrokes 0 BACKSPACE U BACK- 
SPACE T request an exit from editing. The line 
is saved unchanged even if characters have already 
been typed. 


It is possible to abort the line editing process— 
whether or not you’ve already typed in changes. 
To exit from editing, all you do is enter 0 BACK- 
SPACE U BACKSPACE T. You must enter this 
sequence of characters and backspaces consecutive- 
ly. Even if you space over to the right and acciden- 
tally, or intentionally, type in more characters, the 
system will recognize the 0 BACKSPACE JU 
BACKSPACE T sequence when you enter RE- 
TURN. 










) or )0 In immediate execution mode, requests one-pass editing 
of the previous APL line. The system displays the last 
line of APL and leaves the cursor at the end of it. 


[m00] In function definition mode, requests one-pass editing of 
the line numbered m. The system displays the line and 
leaves the cursor at the end of it. 
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Command 











)n 






[mOn] 






/ or ALPHANUMERICS 












. or, 









[/ ALPHANUMERICS] . [TEXT] 






[/ ALPHANUMERICS] , [TEXT] 








0 BACKSPACE U BACKSPACE 7 














Description 


re 


In immediate execution mode, requests two-pass editing 
of the previous APL line. The system displays the last 
APL line and puts the cursor on the following line at 
the position designated by n. 


In function definition mode, requests two-pass editing of 
the line numbered m. The system displays the line and 
puts the cursor on the following line at the position 
designated by n. 


During two-pass editing, each slash or alphanumeric 
serves to show where a character is to be deleted or one 
or more blanks is to be inserted. But those slashes and 
blanks that are to the right of the first dot or comma do 
not have this effect; they’re text to be inserted. Each 
slash deletes the one character above it. Each alpha- 
numeric inserts blanks to the left of the character above 
It. 





The digits 1 to 9 insert the corresponding number of 
blanks. The letters A to Z insert blanks according to the 
code: A equals five, B equals ten, C equals fifteen, etc. 


During two-pass editing, the presence of a dot or a 
comma causes the system to treat the modification in 
three fields. To the left of the first dot or comma, slashes 
or alphanumerics cause deletions and blanks. To the 
right, all characters are inserted as a consecutive block. 


The first dot or comma shows where the insertion is to 
go. The entire block of text to the right is inserted to 
the left of the character marked by a dot or comma. 


Terse editing: Deletes or inserts as explained. The 
system acts on the modified line without displaying it. 


Serial editing: Deletes or inserts as explained. The 
system displays the line as modified, and then waits with 
the cursor on the following line at the position marked 
by the comma on the first pass. Further changes can be 
made with comma, dot, or neither. 


Escape sequence: An entry containing these five key- 
strokes, consecutively and in sequence, is a request to 
abort editing. The original line is retained unchanged, 
even if you’ve already made some partial modifications 
(with comma) or have typed other characters on the 
same line with the escape sequence. 
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After line editing has been aborted, the system 
returns to what it was doing before you started. 
If you were in immediate execution mode, the cur- 
sor returns to the usual APL indent position. The 
keyboard is turned over to you. Your previous line 
of APL will be saved unaltered, regardless of what 
else you typed on the line before entering O 
BACKSPACE U BACKSPACE T. If you are in 
definition mode, the system displays the next line 
number (in brackets) and awaits a func- 
tion-editing instruction. 


Line editing with suspended functions 


A line of entry which ultimately invokes a sus- 
pended function is not directly available for edit- 
ing. It remains intact and unaltered, and you can- 
not recall it with ) or )m until you clear the ap- 
propriate levels of the state indicator. Entering a 
naked branch + clears a suspended function from 
the top of the state indicator, but doesn’t affect the 
line of input which invoked it. Enter as many > 
as necessary to get to an appropriate level of the 
state indicator. Then ) or )n recalls the line which 
invoked the suspended function you last cleared. 


If, while in immediate execution mode, you enter 
a line of APL which results in a suspended func- 
tion, you can’t retrieve that line with a ) or )n 
until you’ve cleared the appropriate level of state 
indicator. After a function becomes suspended, if 
you enter a ) to recall your previous APL line, 
it appears as if there is none. The cursor simply 
returns to the standard APL indent position. 


You can use the system command )SJ to request 
display of the state indicator. Then you can enter 
> successively until you reach the desired level of 
the state indicator. Note that if you enter addition- 
al statements while in the suspended state, you do 
not affect the ability to recall the line which result- 
ed in the suspension. 


This feature of the system can be useful in retriev- 
ing a problem line without retyping it. Note that 
the system command )RESET clears the entire 
state indicator stack including the last line of im- 
mediate input. 


Common errors 


Exceeding DPW: If you request editing using a 
right parenthesis and a number which exceeds the 
value of DPW, the system responds with the mes- 
sage ALREADY SIGNED ON SHARP APL SYSTEM. 


If you attempt to make insertions that would make 
your line longer than permitted by PW and you’re 
using a form of editing which requires display, the 
system rejects your request with the message 
CHAR ERROR. Then it displays the last valid ver- 
sion of the line. The cursor waits on the same line 
in the first available position to the right. You can 
continue by appending characters to the right or 
overstriking blanks. If you press RETURN with- 
out making any additional changes, your line 
remains as it was before you started the editing 
sequence that elicited the CHAR ERROR. 


Inserting blanks you didn’t intend: If the cur- 
sor is positioned too far to the right (either 
because you spaced over too far, or because you 
used an excessive cursor position when you entered 
line-editing mode) and you then use BACK- 
SPACE to move it back to the left, those blanks 
are still part of the line unless you explicitly 
erase them (with LINEFEED or ATTN). The 
input line goes all the way to the rightmost excur- 
sion of the cursor. That’s true regardless of wheth- 
er you spaced over there yourself, or the system 
did it for you when you used an excessive number 
to the right of ). 


To avoid the inclusion of unintended blanks, if you 
type a dot or comma that’s to the left of an earlier 
cursor position, use a combination of SPACE or 
BACKSPACE to position the cursor where you 
want it and then press LINEFEED. Now you can 
type the desired characters and press RETURN. 


Illegal overstrikes: Illegal overstrikes during 
line editing are treated in the same way as in any 
other situation. That is, when you accidentally 
overstrike one character with another to form a 
combination that is meaningless to APL, the 
system rejects your entry with the message 
CHAR ERROR. It displays your entry up to that 
point, and waits for you to complete it correctly. 
If you prefer to abort line editing, enter 0 BACK- 
SPACE U BACKSPACE T. 


71 MODES OF INTERACTION AT A TERMINAL 


Evaluated input O mode 


The symbol ( stands for the terminal. If you 
specify a value for D, as in (+X, you are sending 
a value to the terminal for display. If you refer 
to a value of D, as in X+{], you are requesting the 
value of a line to be entered from the terminal. 


When in the course of executing an APL state- 
ment the interpreter encounters a reference to 0 
(“quad”), it takes this to mean, “Substitute for 
O the value found by executing one APL line en- 
tered from the terminal.” The system then switch- 
es into evaluated input mode. 


What the system is looking for is one value that 
it will get by executing the line that you enter. If 
your response is a line that contains several state- 
ments separated by diamonds, the value returned 
to [] is the value returned from the last of the 
statements that the system actually executes. It 
might not execute them all if execution is cut short 
by a branch statement within the line you enter. 


Enter [] mode: The signal to switch into Oo 
input mode is a reference to [ in the line being 
executed. 


To mark the fact that it is in O mode and is 
waiting for you to enter a line of APL from the 
keyboard, the system displays the characters QO: at 
the left margin, and then turns the keyboard over 
to you with the cursor at position 7 of the line 
below. For example, if the statement being execut- 
ed is 2x[], you’d see the following sequence: 


2x0 
D: 

3x4} Line you enter in response to [: 
24 


The usual sequence of events is this: the system 
encounters a [] in a statement it is executing. It 
issues a request for evaluated input from the ter- 
minal, marked by the prompt []:. You enter an 
APL expression. The system evaluates it. The re- 
sulting value is substituted for D. The brief excur- 
sion into evaluated input mode is completed. 
Execution of the statement proceeds. 


Q input requires a value: Suppose you enter an 
expression that, when executed, returns no value? 


That’s not an acceptable response. The system in- 
terrupts execution with = the message 
VALUE ERROR. 


Suppose that instead of supplying an APL expres- 
sion, you enter a system command. That’s not a 
response at all. The system executes the command, 
and then it reissues the request for evaluated 
input. 


Suppose you don’t supply any line at all, but, in 
response to the prompt []:, you simply press RE- 
TURN. The system reissues the prompt and again 
awaits your entry. 


Suppose the last (or only) statement of the line 
you enter is a branch. This is not a valid response. 
The system rejects that reply with the message 
SYNTAX ERROR, and reissues the request for 
evaluated input. 


Leave evaluated input mode: You can leave o 


input mode in any of the following ways: 


1. Satisfy the request, by entering a line of APL 
which returns a result. Control returns to the 
statement being executed. What mode you’re in 
next depends on what happens next as execution 
proceeds. 


2. Enter a line of APL which doesn’t satisfy the 
request (because it doesn’t return a result). That 
causes an interrupt; the system reports a VALUE 
ERROR, and returns you to execution mode. 


3. Key the input-interrupt sequence 0 BACK- 
SPACE Y BACKSPACE T, which interrupts exe- 
cution of the line containing the Q, and returns 
you to execution mode. 


4. Enter the right arrow > alone. That causes the 
system to abandon completely execution of the 
APL keyboard entry whose execution led to the 
request for evaluated input. You’re then back in 
execution mode. 


If the Q was found in the line just keyed in for 
immediate execution, then it’s just execution of 
that line that is abandoned. 


But if the [ occurred in a line within a program, 
and that program in turn was evoked by a line in 
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another program, the entire sequence is aban- 
doned. All pendent functions are removed from the 
state indicator, back to the preceding suspended 
function (marked in the state indicator by an as- 
terisk ). 


Character input [© mode 


Like D, the symbol [ stands for the terminal. If 
you specify a value for M, as in +X, you are 
sending data to the terminal for display. If you 
refer to I, as in X4, you are requesting the system 
to get a line of characters from the terminal. 


When in the course of executing an APL state- 
ment the interpreter encounters a reference to M 
ae ” bs = 6 a 
(“quote-quad”), it takes this to mean, Substitute 
for © the line of characters at the terminal, includ- 
ing both the prompt (if any) and the response 
entered from the terminal.” The system then 
switches into character input mode. 


The signal to switch into M input mode is a 
reference to T in the line being executed. 


The system does not mark the fact that it is in 
M mode and is waiting for you to enter a line of 
characters from the keyboard. It simply turns the 
keyboard over to you with the cursor located wher- 
ever it happens to be. This means that it’s your 
responsibility (if you’re the author of the pro- 
gram) to know where the cursor is before issuing 
a request for [] input, or to display a prompt that 
informs the person at the terminal what sort of 
input is expected. You do that by specifying M 
(with a phrase such as [-'ENTER NAME’: t) be- 
fore you refer to M with XA. 


If at the terminal you find the keyboard turned 
over to you while the cursor is on the same line 
as a display, or while the cursor is at the left 
margin, you can be pretty sure that the system is 
in [|] input mode (or possibly arbitrary input 
mode). In any event, it isn’t in execution mode or 
in definition mode. 


Prompt is part of the result: What the system 
returns as the value of [ includes both the charac- 
ters that you enter from the keyboard and also 
any characters that the system displayed on the 
same line, provided that they were displayed by 


any preceding uses of f output. For brevity, in the 
rest of this paragraph, call that display “the 
prompt,” even though strictly speaking the dis- 
played line may have been produced by several 
uses of ( output, or may be only the last line of 
a multiline display. 


The system treats the prompt as though it were 
part of your input. You can even backspace over 
characters in the prompt to form overstrikes. But 
the display characters that are treated as part of 
the input are only those from preceding uses of 
[ output, and only if there was no intervening use 
of DARBIN or QARBOUT. 


The usual sequence of events is this: the system 
encounters a [ in a statement it is executing. It 
turns over the keyboard to you for one line of 
input. You enter any characters. That array of 
characters is substituted for i. The brief excursion 
into character input mode is completed. Execution 
of the statement proceeds. 


If the resulting line is a single character, it is 
considered a scalar. Otherwise it’s a character vec- 
tor. 


Notice that in this mode, whatever you write is 
taken as character data. You can write characters 
that form an APL expression or system command, 
but they won’t be executed because the system 
treats this entry strictly as character data. 


To leave character input mode: 


1. Enter some characters. When you press RE- 
TURN, character input is complete, and control 
returns to the statement that contained M. 


2. Enter the escape sequence 0 BACKSPACE VU 
BACKSPACE T. That causes an interrupt. The 
system returns to immediate execution mode. 


Arbitrary input mode 


Like character input mode, arbitrary input takes 
one line of entry from the terminal. But instead 
of recording what APL characters you enter, arbi- 
trary input records the sequence of codes you 
transmit from the terminal. The result appears as 
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a numeric vector. Each character transmitted from 
the terminal is translated into a number. A table 
showing the significance of these numbers for 
ASCII and for certain other IBM-coded terminals 
appears later in this chapter. 


The switch to arbitrary input mode occurs when 
the system executes an expression such as 
X+{JARBIN Y. Both the argument and the result 
of DARBIN are numeric vectors. (You can also use 
a character argument; each character represents a 
0-origin position in DAV. See the definitions of 
UARBIN and QARBOUT.) The argument indicates 
what codes should be transmitted to the terminal 
before the keyboard is turned over to you. The 
result indicates what codes were received back 
from the terminal, up to (and including) the first 
time you press RETURN. 


Arbitrary input mode permits your program to 
receive from the terminal any sequence of charac- 
ters or control codes. The transmission may in- 
clude control codes or overstrikes that would be 
unacceptable as APL characters. Of course, it’s up 
to the program that receives them to figure out 
what they mean, for instance by keeping track of 
the amount of displacement implied by each key- 
stroke in order to calculate what pair of characters 
must appear at the same place in the display at 
the terminal. 


The system does not mark the switch into arbi- 
trary input mode: It simply transmits to your 
terminal whatever codes were indicated by the ar- 
gument Y, and then turns over the keyboard to 
you, with the cursor wherever it happens to be. 


Leave [JARBIN mode by pressing RETURN. The 
escape sequence O BACKSPACE Y BACKSPACE 
T is not effective during arbitrary input, and sim- 
ply appears as part of the result. 


Background regarding transmissions 
to and from a terminal 


Your terminal communicates with the system, and 
the system replies to your terminal, by transmit- 
ting a sequence of binary codes. Some of these 
codes represent the characters you’ve keyed at the 
terminal, or the characters that the system is send- 
ing back to you for display. Others are used for 
control purposes. Some don’t mean anything to the 


system. Some have no effect when received at your 
terminal. 


In most situations, the business of encoding and 
decoding transmissions is entirely automatic. From 
your point of view, you need only press a key 
marked A at your terminal and somehow or other 
A is received at your active workspace. But in a 
few cases you would like to gain explicit control 
of the transmission sent to your terminal. You 
need that when you want to produce an action at 
the terminal that isn’t confined to displaying char- 
acters from the APL character set. Similarly, you 
may want your active workspace to receive signals 
based on something you did at the terminal other 
than keying recognized APL characters. 


There are several different systems for encoding 
transmission between a terminal and the compu- 
ter. When you sign on, the first thing the system 
must do is decide what transmission protocol your 
terminal is using. It needs that information in 
order to interpret the transmissions it receives from 
you, and to transmit to you codes that will produce 
the appropriate action at your terminal. 


At present, the SHARP APL System recognizes 
five different encodings for communication with 
terminals. Which of the five you're using is report- 
ed in the twelfth element of the result of 
2 (WS 3. The possibilities are as follows: 


0 No encoding needed 
(N-task or B-task) 


1 IBM correspondence encoding 

2 IBM BCD encoding 

3 TY33 (64-character ASCII) encoding 
4 Typewriter-pairing ASCII encoding 

5 Bit-pairing ASCII encoding 


The arbitrary input/output facilities represent 
each of the possible transmitted characters by a 
number in the range 0 through 127. The transmit- 
ted character is based on the 7-bit binary represen- 
tation of that number. The table shows each of the 
128 possible codes for four of the five encodings 
that SHARP APL recognizes, together with the 
significance of each. Note that what action a ter- 
minal takes when it receives a sequence of these 
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codes is governed by the way it is built or con- Note about carriage return: The term “car- 


figured, rather than by anything the APL system riage return” is used in two different senses, 
does. Refer to the documentation supplied by the depending whether you’re referring to an APL 
terminal manufacturer. character or to a transmission code. Within a 






Correspondence between integers 0-127 
and terminal transmission characters 
for IBM encodings and ASCII encoding 







IBM ASCII IBM ASCII 
Corre- type- ASCII Corre- type- ASCII 
spon- IBM writer- bit- spon- IBM writer- bit- 
dence BCD pairing pairing dence BCD pairing pairing 




























NULL 
START HDG 
START TXT 
END TEXT 
EOT 
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HORIZ TAB 
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VERT TAB 
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-CR 
SHIFT OUT 
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DEV CTRL 1 
DEV CTRL 2 
DEV CTRL 3 
DEV CTRL 4 
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SUBSTITUTE 
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FILE SEP 
GROUP SEP 
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IBM ASCH 

Corre- type- ASCII 
spon- IBM writer- bit- 
dence BCD pairing pairing 


| 
I 
Mm Der 


N > AH VV IA 
>< KH VV IAA 


a 
a 
Q 
Q 


-Tmn eU)? 


N> VEC ene | 


e g> 


V 
A 
1 
O° 
' 
o 
| 
7 
O 
* 
2 
P 
F 
+ 
U 
Ww 
> 
4 
c 


BYPASS 
LF 
EOB 

in X 





workspace, APL recognizes a character referred to 
as “carriage return.” It’s DAV[156+070]. If you 
display it at a terminal (without using arbitrary 
output) it has the effect of moving the cursor to 
the beginning of the next line. 


The act of moving to the beginning of the next line 
is produced in different ways in IBM-encoded ter- 
minals and in ASCII-encoded terminals. At an 
IBM terminal, the system transmits the single 


IBM ASCII 

Corre- type- ASCII 
spon- IBM writer- bit- 
dence BCD pairing pairing 


D S * OH—O -0o 


AN, 


RESTORE 
NEW LINE 
BACKSPACE 
IDLE 


NESTE NSCHHBDOVOS SORWNTOHNAOORWR 


ae : { 
PUNCH OFF | 4 
TAB 
START IC | $ | + 
DELETE DELETE 


character called “newline.” At an ASCII terminal, 
the system transmits first the character called “car- 
riage return.” That moves the cursor back to the 
beginning of the line it is now on. Then the 
system transmits a “linefeed” character. 


Encodings for ASCII terminals: Each character 
transmitted consists of eight binary bits. The last 
seven bits are the binary representation of the 
number that you supply as the argument of 
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OARBOUT or QARBIN, and that the system returns 
as the result of QARBIN. 


The eighth (high-order) bit is a parity bit. The 
parity bit is transmitted as a check on the validity 
of transmission. It indicates whether the number 
of 1s in the character is even or odd. 


For devices that expect what is called even parity, 
the total number of 1s in each character (including 
the parity bit itself) must be even. Hence, to 
achieve even parity, the eighth bit must be 1 when 
the sum of the other seven bits is odd, and 0 when 
that sum is even. If X stands for the seven bits, 
then z/X gives you the eighth. 


In transmission to ASCII terminals, GARBOUT and 
OARBIN accept arguments in the range 0 through 
511. In each case, the last seven bits of the trans- 
mitted character are (702)1T128|Y. In transmis- 
sion to an ASCII terminal which is directly con- 
nected to the system transmission control without 
going through the SHARP APL network, the 
system supplies the parity bit automatically, ac- 
cording to the following rule: 


Range Eighth bit 
0-255 Even parity 


256 383 


Set to 0 (space) 


384 511 Set to 1 (mark) 


Transmissions that pass through the SHARP APL 
network (including its link to other networks such 
as Tymnet and Telenet) are always sent with even 
parity. 


In receiving transmission from the terminal (the 
result of DARBIN) you don’t see the parity bit. 


Notice that in any event only the last seven bits 
of each character are significant, and in effect, the 
system treats all arguments modulo 128. Thus, an 
argument of 65 sends the same character as an 
argument of 193 or 449. 





Encodings for IBM terminals: The IBM en- 
coding uses six rather than seven significant bits. 
That means that a transmission can use only 64 
distinct characters. The range of possible signals 
is increased to 128 by having two signals that 
mean “What follows should be interpreted as 
upper-case” and “What follows should be inter- 
preted as lower-case.” (Each transmission is as- 
sumed to start in lower-case unless otherwise 
marked; an IBM terminal usually includes a 
device that returns it to lower-case at the end of 
each transmission. ) 


When you’re transmitting between your work- 
space and an IBM-encoded terminal, you do not 
have to provide explicit up-shift or down-shift 
characters, nor do you have to interpret the effect 
of shift characters in what you receive from the 
terminal. The system does that for you. 


To indicate that you’re sending a lower-case char- 
acter, in the argument of QARBOUT or DARBIN you 
use a value in the range 0 through 63. To indicate 
that you’re sending an upper-case character, you 
use a value in the range 64 to 127. The system 
keeps track of what shift is implied by the values 
you supply, and inserts the appropriate shift char- 
acters where they are needed. Similarly, in each 
transmission received from the terminal, the 
system removes the shift character, and generates 
a value in the range 0 through 63 for a character 
transmitted while the terminal was in lower-case, 
and in the range 64 to 127 for a character trans- 
mitted while the terminal was in upper-case. 
(That even applies to control characters, so the 
result of DARBIN discriminates between CAR- 
RIAGE RETURN pressed while in lower-case 
and CARRIAGE RETURN pressed while in 
upper-case. ) 


The seven-bit character used to control transmis- 
sion to an IBM terminal thus uses the last six bits 
for the character. A seventh bit is used for parity. 
The system automatically inserts a bit to supply 
odd parity. However, you won’t see that bit in the 
workspace. What appears in the workspace to be 
the seventh bit is used to indicate upper or lower- 
case. 
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Explicit control of turn-around 


With arbitrary input and output, the system does 
not supply the characters that in other situations 
are sent automatically at the beginning and end 


These functions refer to the global variables 
ARBTYPE, ARBBIT, ARBCORR, and ARBBCD, which 
may be found in workspace 1 ARBOUT. Their use 
is explained in the paragraph on the right argu- 
ment of QARBOUT and DARBIN. 


of a transmission. For instance, at an IBM termin- 
al, it’s your responsibility to transmit explicitly the 
characters known as “circle-D” and “circle-Q” 
which determine whether the terminal expects that 
what follows is something it should print or is a 
control sequence. When you’re receiving from an 
ASCII terminal, it’s your responsibility to move 
the cursor to a new line following the RETURN 
which marks the end of the entry. 


Example of use of the function ARBINIBM: Sup- 
pose you wish to collect arbitrary input from a 
terminal that uses the BCD encoding. You want 
the terminal to print the message MAKE YOUR 
ENTRY and then assign to the variable X a record 


To illustrate how explicit controls might be used, 
there follow two skeletal definitions for functions 
to issue a prompt and then receive arbitrary input, 
one for an ASCII terminal and the other for an 
IBM terminal. 





Z*ARBINASCII PROMPT; REF; TERM; LF; DIO 
[1] OI0+0 

[2] LF+10 

[3] TERM«(2 [WS 3)[11] 

C4] 2 (TERM=4)/'REF<ARBTYPE' © &(TERM=5)/'REF*+ARBBIT' 

[5] 2 (021t0pPROMPT )/ 'PROMPT<+128 | REF PROMPT' 

[6] Z4[]ARBIN PROMPT a ASCII TERMINAL IS THEN READY TO TRANSMIT 
C7] A USER ENTRY ENDS IN <RETURN> [BUT NOT NEW LINE] 


[8] QARBOUT LF a SEND LF TO COMPLETE <NEW LINE> SEQUENCE 
V 














Z*ARBINIBM PROMPT; CIRCLEC ; 
[1] DI0+0 

[2] CIRCLEC+15 © CIRCLED+11 

[3] TERM<(2 [WS 3)[11] 

[4] 2 (TERM=1)/'REF+ARBCORR' © 2(TERM=2)/'REF+ARBBCD' 

[5] 2(0#1+0pPROMPT ) /' PROMPT<128|REF1PROMPT" 

[6] Z+(JARBIN PROMPT ,CIRCLEC a UNLOCK KEYBOARD TO GET INPUT 
[7] A USER ENTRY ENDS IN <RETURN> = NEW LINE 


[8] OARBOUT CIRCLED a CHANGE STATE OF 2741 FROM <RCV CONTROL> TO <RCV TEXT> 
y 


CIRCLED; REF; TERM; DIO 
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of the response received. The following shows 
what you get if the response is HOW? 


X+ARBINIBM ‘MAKE YOUR ENTRY ' 
MAKE YOUR ENTRY HOW? 


X 


41 56 38 28 118 109 15 


TOTEN 


oD H O W ? NL(UC) EOT 


Watch out: Output that the system prepares au- 
tomatically frequently contains “idle” characters. 
Great care is taken to calculate the number of idles 
that the terminal requires to give it time to com- 
plete one part of its physical activity before at- 
tempting to start the next. When you use arbitrary 
output, you are transmitting to your terminal 
without the benefit of the system’s calculations of 
the number of idles the terminal will need. Before 
you start doing that, it’s important to study the 
device to which you’re proposing to transmit. 
Make sure that you include adequate provision for 
idles. While the details vary from terminal to ter- 
minal, it is quite possible to send to a terminal, 
transmissions that it will be unable to handle 
properly, or which may even be damaging to it. 
Refer to the manual provided by the manufacturer 
of the device. 


Appending normal output to a file 


The system function DOUT lets you append to a 
file all output that would otherwise be displayed 
at your terminal. You can append output to the 
file instead of or in addition to having it dis- 
played at your terminal. 


As a side-effect of DOUT, the system sets the value 
of a task parameter which controls what it does 
with your output. That parameter remains in ef- 
fect for as long as the task lasts, or until you give 
it a new value by again using HOUT. 





Some possible applications of DOUT 


1. Use DOUT to “capture” terminal output. Sup- 
pose you have a system that uses considerable 
CPU and connect time to create a report. At pre- 
sent you get the report printed at your terminal 
as the work progresses. A system like that may be 
subject to expensive reruns if there are minor line 
problems, if the paper does not feed properly, or 
if some detail in the report is not correct. By cap- 
turing the output on file but not displaying it until 
later, you can get the critical CPU and connect 
part of the job done more quickly with less chance 
of interruption or failure. When you're ready to 
do so, you can print the report at your terminal, 
using a function that’s inexpensive, and easy to 
restart or rerun if need be. If some detail is wrong 
(e.g. a mis-aligned heading) you can fix it and 
print it correctly without needing a complete 
rerun. 


2. Use DOUT to capture output from systems that 
were not designed to provide data for further ma- 
nipulation. 


Suppose you have a system that prints a report but 
doesn’t store what’s reported as an accessible data 
array. Now you need to treat the reported data as 
input to some other application. Without OUT 
you'd have to modify the application (which might 
be hard to do, or even impossible if the functions 
are locked). Using DOUT you can capture the re- 
port on file. After that you can manipulate it as 
need be. 


3. Use DOUT to provide support for graphic dis- 
plays at a CRT terminal. With the output on file, 
you can easily recall images that have vanished 
from the screen. This is a case in which you want 
the output to go both to the terminal and to the 
file. 


4. Use DOUT to convert an existing system that 
now runs as a T-task so that it can run as an 
N-task or B-task. Moreover, using [OUT can con- 
siderably simplify the design and implementation 
of a new system to run as an N-task or B-task. 
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5. Use DOUT so that a program that currently 
prints reports on the terminal uses HSPRINT in- 
stead. It also considerably simplifies the design and 
implementation of a new system to use 
HSPRINT , since you can get output at the terminal 
while you’re debugging, and then during produc- 
tion direct it to the file for remote printing. 


6. Use [OUT to suppress terminal displays gener- 
ated as side effects of a program that you want to 
use but which you can’t conveniently control (for 
example, because it’s locked). 


Whenever you do something that generates output, 
the system consults the [OUT parameter to see 
what should be done with it. If the second element 
is something other than 0, it attempts to append 
the output to the file tied to that number. If there 
is no file tied to that number, you'll get the mes- 
sage FILE TIE ERROR. If there is a file tied, you 
must have APPEND access to it with a 0 passnum- 
ber; otherwise, you'll get the message 
FILE ACCESS ERROR. And the file must have 
space to receive the components that will be ap- 
pended, or you’ll get the message FILE FULL. 


Note that sending output to a file and sending it 
to the terminal are controlled independently; it’s 
possible to have one or the other, or both, or neith- 
er. 


Effect of an error: The DOUT parameter is not 
affected by a halt in execution produced by an 
error or an interrupt. 


System error messages are not subject to the 
DOUT parameter. That is, regardless of your use 
of DOUT, error messages are always directed to the 
terminal, and never appended to a DOUT file. 


If the system halts execution of a function because 
of an error while output is not being displayed but 
is being appended to a file, you'll see the error 
message at the terminal. However, the error does 
not itself alter the setting of the DOUT parameter. 
If you attempt to display variables in order to 
diagnose the problem (but leave DOUT the way it 
was) the displays you request will continue to go 
to the file and not to the terminal. Hence, in a 
situation such as this, the first thing to do is to 
execute [JOUT 1 0 until you’re ready to resume 
execution of the job. 


Timing of change in [OUT parameter: A 
change in the destination of output takes effect 
before the system returns the result of OOUT. Sup- 
pose you have a file tied to 99, and you execute 
the following sequence: 


Hour o 99 

2x3 

DOUT 10 
0 99 


The first line specifies that output should be sent 
not to the terminal, but to file 99. But the expres- 
sion GOUT 0 99 has a result. Since the result is 
not assigned to a variable, it must be displayed. 
But because DOUT 0 99 is already in effect, the 
display is sent not to the terminal, but to the file. 


The second line computes 2x3. The result, 6, is 
appended to file 99. 


The third line discontinues output to the file, and 
reinstates output to the terminal. The result is 


0 99. It appears at the terminal but not in the 
file. 


Watch out: When you start sending output to 
a file, if you don’t want the result of DOUT to be 
appended to the file, assign that result to a vari- 
able, by using JUNK+{]OUT 0 99 rather than just 
DOUT 0 99. 


Effect of DOUT on prompted input: While 
DOUT is causing output to be appended to a file, 
the file will contain prompts issued by using [M 
output, but not the replies received from the ter- 
minal as [ input. 


However, when you use DARBIN, the file contains 
both the prompt and the response. These are 
preceded by a control message indicating that the 
two following components are DARBIN prompt and 
response. 


Control messages in a [OUT file: Certain kinds 
of output are given special treatment when written 
to a OUT file. For each instance of such output, 
the system automatically appends to the file a 
component containing a control message. Follow- 
ing the control message, the system appends one 
or more components containing the data. 
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OO ee 


_~ 


A control message appears only as a component 
of the DOUT file, and not in the display at the 
terminal. 


Control statements appearing in a DOUT file are 
acceptable to the highspeed printer facility 
HSPRINT. They are also acceptable to the function 
[PRINT in workspace 1 HSPRINT. Thus, 
HSPRINT can reproduce at the highspeed printer, 
and TPRINT can reproduce at a terminal most ter- 
minal output recorded in a DOUT file. 


Control messages 


A control message is an array to which certain 
system functions attach a special significance. A 
control message is written as a component of a file; 
it serves to explain how to interpret the compon- 
ents that come after it. 


Four types of control messages are generated au- 
tomatically while you are writing files using 
DOUT. Other control messages must be explicitly 
generated. The font types that are generated au- 
tomatically are: 


t- ie Quad-prime output 
2. DFMT Quad-FMT 


(But only when (FMT is the root 
function of the statement) 


3. QARBOUT Arbitrary output 


4. (ARBIN Arbitrary output and input 

The highspeed printer facility makes extensive use 
of control messages, including both messages gen- 
erated automatically by DOUT and other messages 
that are specific to work with the printer. The 
workspace 1 HSPRINT contains functions to gen- 
erate the control messages needed to operate var- 
ious printer controls. 


Format of a control message: A control mes- 
sage is not inherently different from any other 
kind of data. Rather, the use of control messages 
is a convention shared by OOUT, HSPRINT and 
TPRINT. The same convention is likely to be fol- 
lowed in developing other control messages in the 
future. 


A control message is a 22-element character vector 
with the following format: 






Position Field name and content 


ial 
1 ~4+94V This character can’t be dis- 
played at a terminal, and is shown as 
the canonical unprintable character 


0 













Message Number: A four-digit 
number identifying the type of control 
message. Numbers start at 0000 and 
are always leading zero filled. 


Blank. 












Component Count: A four-digit 
number specifying the number of fol- 
lowing components controlled by this 
control message. Numbers start at 
0000 and always include leading 
zeros. 


Blank. 





Mnemonic: Text describing the 


control message. 


12-22 


Component count: 


The component count in- 
dicates how many of the components that follow 
are described by this control message. For exam- 


ple, suppose you have a program in which the 


following statement occurs: 
F OFMT (A;B;CxD) 


If you execute that statement while DOUT is set to 
append output to a file, the file will contain a 
control message indicating that you used (FMT out- 
put and that four components will be used to con- 
tain the arguments of DFMT. (That’s one compon- 
ent for the left argument, and one each for the 
three arrays in the right argument.) The control 
message itself will be the following 22-element 
vector: 


0000 0004 FORMAT 
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The first component following that will contain 
the value of F. The second will contain the value 
of A, the third the value of B, and the fourth the 
value of CxD. 


List of control messages: The following is a list 
of control messages that were current at the time 
this manual was prepared: 









Number Mnemonic Description 
Ee 
0000 FORMAT Arguments to (FMT follow. 















0001 MIXED Arrays for mixed output fol- 
low. 






0002 PAGEN New page number follows. 









QUADP [M output follows. 





TRANSLATE A translate table follows. 





0005 DIGITS New value for [PP follows. 








WIDTH New value for DPW follows. 








TITLE 





A page title follows. 





SUBTITLE A page subtitle follows. 







0011 PAGE Skip to beginning of a new 
page. 






CARRIAGE Vertical forms control. 





PRTARBOUT Switch to print/noprint 
ARBOUT data. 








ARBOUT ARBOUT argument follows. 






0015 ARBIN Prompt and result follows. 





An up-to-date list may be found in the current 
revision of SATN-2, available on-line in the work- 


space 1 SATN. 


dey 
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Chapter 11: 


SHARED VARIABLES 
FOR COMMUNICATION 


BETWEEN 
WORKSPACES 





Your active workspace can communicate with 
another active workspace when it shares a vari- 
able with it. A shared variable is one that is 
common to your active workspace and the active 
workspace of another task. 


Sharing is always pairwise. It takes place only by 
mutual agreement between two workspaces. While 
it’s possible to set up a network with many parties, 
that network is made up of links each of which 
has only two end-points. 


Sharing with whom? Workspaces and auxiliary 
processors: It’s possible to share a variable (or 
several variables) with any other workspace that’s 
active at the same time yours is. In principle, you 
could use shared variables to communicate with 
the active workspace of any other task running at 
the same time, whether it be an N-task, B-task, 
or T-task; whether that task be another task of 
your own, one belonging to another user, or one 
run by the steward of a public workspace. But 
sharing is always voluntary, and never takes place 
until both of the participating workspaces have 
agreed to share. 


It’s also possible to share variables with a program 
that is completely outside APL. That raises the 
possibility that an APL user, working as usual 
within an APL environment, may make use of 
facilities that are outside the APL system itself, 
and which perhaps provide quite different services, 
or operate in a quite different language. This is 
possible provided the non-APL program is run- 
ning at the same computer facility at the same 
time and follows the rules for communicating with 
the APL system’s shared variable processor. 


From the point of view of the APL user, such a 
program, running outside APL but communicating 
by shared variables, is called an auxiliary proces- 
sor. An auxiliary processor might be a file access 
mechanism, or a utility such as file-sort or print, 
or a language compiler, or almost any special- 
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EXAMPLE: EVENTS IN YOUR WORKSPACE AND IN YOUR PARTNER’S WORKSPACE 
BEFORE AND AFTER YOU SHARE A VARIABLE X 


Your Active Workspace 


Your Partner’s Active Workspace 


X 
VALUE ERROR 

X 

A 


Sharing established between you and your partner 


X«'ABC! 





purpose program of sufficient interest and benefit 
to warrant an interconnection with APL. Just 
which auxiliary processors are available—or 
whether any are at all—depends on the system’s 
managers. 


It doesn’t matter with whom or what you share 
a variable: the functions used for sharing do not 
differ. In particular, they’re the same regardless 
of whether you’re sharing a variable with an aux- 
iliary processor or with the active workspace of 
another APL task. To cover both those possibili- 
ties, this manual uses the word “processor.” That 


X*2x13 


term is deliberately chosen to refer equally to an 
APL active workspace and an auxiliary processor 
that uses shared variables. The processor with 
whom you share a particular variable is referred 
to as your partner. 


Applications of shared variables in SHARP 
APL: Many applications are possible. The fol- 
lowing are among the most common: 


1. To communicate between your T-task’s active 
workspace and the active workspace of an N-task 
you've started, either to receive back from it results 
it has calculated, or to give it new instructions 
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after it has started. Such an N-task is useful for 
calculations that require more space or more com- 
puting time than would be convenient to include 
in your T-task. 


2. To permit several different T-tasks to commun- 
icate with a common processor. For example, a 
data base administrator may run an N-task which 
shares variables with individuals enrolled in the 
data base, receives and coordinates their various 
requests, and does the actual reading and writing 
of files. Shared variables permit a single N-task 
both to manage contention between different users, 
and to validate or edit what individuals request. 
Following such a scheme, only the N-task may 
actually tie the files involved in the data base; the 
individual users have no need to tie them, to know 
what files are used, or even to know that they 
exist. 


3. To model the interaction of autonomous but 
communicating processes. Shared variables are ex- 
tremely useful for modelling the behaviour of a 
system made of components which work indepen- 
dently but which on occasion communicate 
amongst themselves. 


How a shared variable permits communication 


A shared variable is a single variable which is 
visible both from your active workspace and from 
your partner’s active workspace. A variable that 
two workspaces share is thus what in engineering 
is called an interface. 


When you give the shared variable a new value, 
your partner may then refer to it, and thereby 
receive information from you. Similarly, when 
your partner gives the shared variable a new 
value, you may refer to it, and thereby receive 
information from your partner. (Notice that when 
a variable is shared, you may find that it has a 
different value each time you refer to it, even 
though you never set it at all.) 


No special function for “send” or “receive”: 
When either you or your partner uses the shared 
variable, what each of you sees is its current value. 
When either of you sets the shared variable, that 
changes the current value. 


When you use this property to communicate with 
another processor, there’s no need for a special 
function for an action you might call “put,” 
“send,” or “write,” nor for a corresponding action 
you might call “get,” “read,” or “receive.” The act 
of setting a new value for the shared variable has 
the effect of transmitting it to your partner, and 
the act of referring to the shared variable has the 
effect of receiving from your partner. 


For effective communication in most applications, 
it’s important that the two workspaces keep in 
step. For example, you may want to ensure that 
each time you read the shared variable, your part- 
ner has given it a new value exactly once. If the 
two of you don’t keep in step, the one that’s receiv- 
ing may miss something, or may inadvertently 
receive the same message more than once. Com- 
munication can be appropriately interlocked by 
using access control, described in the sections en- 
titled “State Vector” and “Access Control.” 


How sharing is initiated 


Sharing between you and your partner starts when 
each of you has made an offer to the other. It 
doesn’t matter who offers first. Your offer iden- 
tifies both the processor to whom it’s directed and 
the name of the variable you propose to share. You 
do that by using the dyadic function DSVO. Its left 
argument identifies the processor with whom you 
propose to share, and its right argument contains 
the name (or names) you propose to share. 














For example, suppose there is an active workspace 
belonging to a processor which can be identified 
simply by the number 7844919, and you wish to 
share with it a variable named X. You could ex- 
tend to it an offer to share X by the expression 


7844919 [JSVO 'X' 
Under some conditions, it takes two numbers to 
identify a processor. If you wanted to share X with 


the processor identified as 1618033 3, you’d need 
to enter 


(1 291618033 3) DSVO 'X! 





Before you can make such an offer, you need to 
know the processor’s ID, and what names to share 
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with it. You may have that information by pre- 
arrangement. Or, using the function OSVQ, you 
can inquire what processors (if any) are offering 
to share with you, and what names they propose 
to share. 


General offer: If in the left argument of SVO 
you use a processor ID of 0 (or a 2-element ID 
of 1 2p0 0), you have made a general offer. 
That is, you’ve offered that particular variable to 
anyone. Sharing can be established by any proces- 
sor which replies with a specific offer (that is, one 
whose left argument uses your specific processor 
ID). 


You can’t use a general offer to accept a general 
offer made by someone else. Conversely, if you 
make a general offer, it can’t be accepted by 
someone else’s general offer, but requires a specific 
response. 


Degree of coupling: Each time you use [SVO 
to offer to share a variable with another processor, 
the explicit result is the degree of coupling of the 
name that you offer. You can also use SVO mon- 
adically to inquire about the current degree of 
coupling of a name in your workspace. For exam- 
ple, if you make the offer illustrated in the preced- 
ing paragraph, you might get the result 1: 


(1 2p1618033 3) DSVO 'X' 


Or you might simply inquire about the degree of 
coupling of the names X, Y, and OK, and discover 
that they are respectively 1, 2, and 0: 


USVO 3 2p'X Y OK! 
120 


A degree of coupling may be 0, 1, or 2. The value 
indicates the number of processors which have of- 
fered to share each of the names you mentioned. 


When the degree of coupling becomes 2, you have 
offered the name and another processor has made 
a corresponding offer. Sharing commences. The 
shared variable is then visible both in your active 
workspace and in the active workspace of your 


partner. A value that is set after the degree of 
coupling becomes 2 is visible to either partner. 
Until one of you sets a new value for the variable 
you have just begun to share, each workspace con- 
tinues to contain the former (unshared) value. 


When the degree of coupling for a name (in your 
workspace) is 1, you have made an offer but your 
partner has not. Sharing is not complete, and no 
communication can take place. (When a processor 
has made you an offer that you haven’t accepted, 
that name will have degree 1 for that processor. 
However, in your workspace, that name is still 
quite independent of what anyone else has done, 
and so for you, that name’s degree of coupling 
remains 0.) 


When the degree of coupling is 0, the correspond- 
ing argument is not a name or is not a shared 
variable. 


Note about the terms “use” and “set”: Since 
communication depends upon one partner making 
use of a value that the other partner has set, it’s 
important to maintain a clear distinction between 
the terms used for these contrasting actions. The 
terms “set,” “use,” and “reference” are defined as 
follows: 


1. Each time you use the name of a variable im- 
mediately to the left of a specification arrow, you 
set the variable. (“Set? thus corresponds to 
“write.” ) 


2. Each time you use the name of a variable in 
a position other than immediately to the left of a 
specification arrow, you use the variable. (“Use” 
thus corresponds to “read.”) 


3. Any occurrence of the name of a variable is a 
reference to the variable, and may be either a set 
or a use. An expression such as A+X¥+B contains 
only one reference to X, in which X is set (and A 
receives the result of the specification X+B, which 
is B.) 


4. There are three functions which (while in 
some sense they “use” the value of a shared vari- 
able) do not count as a use for the purposes of 
access control. They are (PACK (which may incor- 
porate the name and value of a variable into a 
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package), 6 DWS (which reports the current value 
of a variable), and 4 [WS (which reports the 
number of bytes occupied by the current value of 
a variable). See also the chapters “System Func- 
tions for Manipulating Packages” and “System 
Functions for Reporting System or Workspace In- 
formation” for discussions of [PACK and [WS with 
a shared variable. 


Initial value of the shared variable: Once 
sharing starts, the shared variable exists in both 
workspaces, and so has the same value regardless 
of the workspace from which you look at it. But 
suppose either or both of you had already estab- 
lished a value for a variable of that name before 
sharing started? That situation is covered by the 
following rules. 


1. If at the time sharing is established, neither of 
you has assigned a value, then the shared variable 
has no value. 


9. If at the time sharing is established, a value has 
been assigned by one of you but not the other, that 
value becomes the value of the shared variable. 


3. If at the time sharing is established, each of you 
had already assigned a value to the variable that 
you now share, the shared value is the value set 
by whichever of you first offered to share the vari- 
able. (Watch out: that’s not necessarily the same 
as saying “whichever of you first assigned a value 
to the variable.” ) 


Regardless of how the shared name comes by its 
initial value, its initial state (as described in the 
section “The State Vector”) is always 0 0 1 1. 


Duration of coupling: Once a share has been 
established (that is, when the degree of coupling 
of a variable is 2), sharing continues until any of 
the following happens: 


1. Either of you retracts the offer to share, using 
the system function (SVR. 


2. Either of you signs off (or is bounced, or ter- 
minated in any other way). 


3. Either of you frees the name in the active 
workspace. Either of you could do that by any of 
the following: 


a. By expunging the name in your active 
workspace. You might do that by using the com- 
mands )ERASE or )COPY, or the functions [EX or 
6 DFD, or by using OPDEF to redefine that name 
(regardless of what new meaning [JPDEF may give 
it). 


Note that when the shared variable is global, if 
you use the command )COPY to replace it by 
another object of the same name, that has the ef- 
fect of expunging the old use of the name, even 
though you thereby replace it by another use of 
the same name. 


b. By terminating execution of a function to 
which the shared name is local. 


c. By replacing the entire contents of the active 
workspace, by a command such as )LOAD or 
)CLEAR, or by one of the system functions 
OLOAD or DQLOAD. 


When you expunge the name of the shared vari- 
able, sharing ceases. You no longer have a way of 
referring to that variable’s value. However, the 
variable continues to be visible in your partner’s 
active workspace, and your partner continues to 
have an offer to share that variable with you. If 
you renew your offer to share that name with the 
same partner, you’ll again be able to see its value. 


Watch out: You may use shared variables for 
some applications for which you also use file ties. 
Notice that the maximum life of a shared variable 
is the duration of the active workspace, whereas 
the maximum life of a file-tie is the entire dura- 
tion of the task. An offer to share never survives 
)LOAD or )CLEAR, whereas a file-tie does. 


Processor ID 


To share a variable, each of the participating 
workspaces must make an offer to the other. To 
do that, each must be able to identify the other. 
You identify an active workspace by its processor 
ID. 
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You need to know your partner’s processor ID, 
and you need to establish a processor ID of your 
own. When you inquire about offers directed to 
you, or make an offer to another processor, you 
don’t explicitly mention your own processor ID. 
However, at that time, the system must be able to 
refer to an explicit ID that identifies you during 
the life of the active workspace you’re using. To 
do that, the system uses a two-element vector. The 
first element is simply your account number 
(usually a 7-digit positive integer). An auxiliary 
processor is assigned a number in a similar way, 
but by convention is given a number between 1 
and 1000. 


Clone ID: The second element of the processor 
ID serves to distinguish between the active work- 
spaces of two tasks running concurrently under the 
same account number. It is called the clone ID. 
The clone ID is a number that an active work- 
space may arbitrarily assign itself. 


If you never run an N-task or a B-task, the clone 
ID won’t matter, since you won’t need to distin- 
guish your active workspace from their active 
workspaces. You can leave unchanged the default 
clone ID of 0, which the system otherwise assumes 
for every new active workspace. 


Even if you run several tasks at the same time, 
the clone ID doesn’t matter until you either in- 
quire about share offers addressed to you (using 
the function OSVQ) or make some share offers 
yourself (using the dyadic form of OSVO). When 
you use either of those functions, you must have 
established a clone ID that distinguishes your pre- 
sent active workspace from the present active 
workspace of any other task using shared vari- 
ables. 


When a workspace is first loaded (and also in the 
workspace you get at sign-on), the clone ID is 
0. Thus, workspaces belonging to N-tasks or T- 
tasks owned by a single account are not distin- 
guishable until they assign themselves distinct 
clone IDs. One of them may retain the clone ID 
O. If none of them explicitly sets a clone ID, 
whichever is first to make a share offer or inquiry 
(that is, to use OSVQ or dyadic QSVO) gets 0 as 
its clone ID. Once one of the workspaces has laid 
claim to 0, none of the others will be able to use 
OSVQ or dyadic OSVo (and hence won’t be able 


to use shared variables) until it establishes a dif- 
ferent clone ID. 


Setting a new clone ID: The function OSVN is 
used to set the clone ID for your active workspace. 
The argument of OSVN is the single integer you 
Propose. For example, to propose the clone ID 
99, you execute: 


OSVN 99 
99 


The result is the clone ID in effect following your 
use of DSVN. If you’ve succeeded in setting a new 
clone ID, the result is the new value. However, 
once you’ve started to make use of your clone ID, 
you can’t revise it unless you retract all your 
shared variables. During use, your clone ID is said 
to be “frozen.” 


If you propose a clone ID that doesn’t distinguish 
your workspace, the function returns the result 
“1 (which couldn’t be a clone ID, since they’re 
restricted to non-negative numbers). 


Freezing the clone ID: As long as you have a 
shared variable, the system freezes your clone ID. 
You can’t set it to anything else. When you reduce 
to zero the number of shared variables in your 
workspace (including variables that may at the 
moment be shadowed), you are again free to 
change your clone ID. (During the execution of 
a function containing a local name, the local mean- 
ing is said to be “visible,” and is said to “shadow” 
other uses of the name.) Sharing a variable with- 
out first setting a clone ID has the effect of freez- 
ing your clone ID at 0. 


If you attempt to use DSVQ or dyadic DSVO when 
your clone ID is the same as one frozen by another 
of your processors, the system rejects your state- 
ment with the error message IDENTIFICATION 
IN USE. That’s an implicit error, since your state- 
ment does not explicitly contain the processor ID. 


Picking a name for a shared variable 


When you make an offer to share, you specify a 
name by which each variable will be known in 
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your workspace. Each name is formed in the same 
way as any other name in the workspace. It can’t 
be a distinguished name (that is, it can’t be one 
of the system names which start with O). It may 
be a name local to a function now in execution. 
In that case, the share will terminate as soon as 
execution of that function terminates. 


A name you propose for use within the workspace 
must have no visible use as a label or as the name 
of a function. It’s all right to offer a name which 
doesn’t yet have any visible use; that is, it doesn’t 
matter whether the variable exists at the time you 
offer its name. The act of offering to share a name 
establishes its nameclass as “variable.” 


Surrogate names: You and your partner may 
refer to the same variable by different names. 
When you state the name by which the variable 
will be known in your workspace, you may also 
state a different name by which your partner may 
refer to it. The second name is called a surrogate 
name. For example, you might propose to share 
a variable which in your workspace is called 
COMMAND but which your partner calls WISH. 


(In the same fashion, your partner may also use 
a surrogate name, so that within its active work- 
space it may use yet another name to refer to the 
variable whose surrogate name is WISH. But the 
surrogate you offer must match the surrogate of- 
fered by your partner.) 


The surrogate name (if you use one) appears to 
the right of the name to be used within your work- 
space, separated from it by at least one blank. For 
example, to offer to 7844919 0 a name which 
you will call COMMAND but which it will see as 
WISH, your entry and its result might appear as 
follows: 


(1 297844919 0) DSVO "COMMAND WISH' 


If your processor ID is 1436713 99, your partner 
could make a matching offer to you. For example: 


(1 291436713 99) DSVO 'WISH' 


Or your partner could elect to use some quite 
different name internally (for example, X) by an 
offer such as 


(1 201436713 99) OSVO 'X WISH' 
2 


The system requires that the last name on each 
row in your offer match the last name in the 
corresponding offer from your partner. That 
remains true whether the last name on each row 
is the only name or is the surrogate name. 


Inquiring about incoming offers 


The function [SVQ permits you to inquire about 
shared-variable offers being made to you. 


When the right argument of QSV@ is an empty 
vector, [SVQ returns a matrix containing the 
processor ID of each processor that has an out- 
standing offer to you. For example, if you execute 
OSVQ 10 and find the following result: 


OSVQ 10 
7844919 0 
1618033 3 


this means that offers to share with your processor 
ID have been made by processors 7844919 0 and 
1618033 3, and are still outstanding. That is, 
you’ve not accepted them and they’ve not been 
retracted. 


When you use OSV@ with a single processor ID 
as its argument, it returns a character array of the 
name (or names) which that processor is offering 
to share with you, but which you have not yet 
accepted. The argument of (JSV@ can only refer to 
one processor. If the argument is a scalar or a 
one-element vector, the system assumes a clone ID 
of O. 


If an active workspace with the processor ID 
1618033 3 has an outstanding offer to you, you 
might execute (SVQ 1618033 3 and get the fol- 
lowing result: 


OSV@ 1618033 3 
X 
WINDOW 
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This means that the processor has made offers 
(thus far unrequited) to share with you the names 
X and WINDOW. 


Ambiguous use of [SVQ or dyadic OSVO When 
you use [JSVQ@ you are in effect asking, “What 
offers are being made to me?” Similarly, when 
you offer to share a variable by using dyadic 
USVO, you are in effect saying “I make this offer.” 
Either of those actions is ambiguous if at the time 
your workspace lacks a unique clone ID. The sys- 
tem rejects such a use with the error message 
IDENTIFICATION IN USE. 


Point of view in the state vector and access 
controls 


When two workspaces share:a variable, sharing is 
symmetric. Neither workspace takes precedence 
over the other. It doesn’t matter which made its 
offer first and which second. 


There are two functions which set or report con- 
trols for the shared variable. Each of them takes 
as its argument or returns as its result a 4-element 
vector. 


In each vector, the first two elements always con- 
cern setting the shared variable, while the last two 
always concern using it. 


Which processor the elements refer to is a matter 
of point of view. The first and third elements al- 
ways refer to the workspace that’s making the in- 
quiry, while the second and fourth always refer 
to the other workspace. 


Your Partner 


You Your Partner You 





Each workspace sees itself in the first and third 
positions, and its partner in the second and fourth 
positions. 


This convention follows ordinary speech: the pron- 
oun “you” does not refer to a. particular person, 
but depends on who is speaking. The first and 
third elements of the state vector or of the access 
vector are in this manual labelled “you,” while the 
second and fourth are labelled “your partner.” 


Keeping track of who’s set what: In many ap- 
plications, to make sure that parts of the commun- 
ication are not lost, it is essential to set an access 
control to prevent one processor from setting 
values that the other can’t use, or from using 
values when the other hasn’t set. 


It may also be useful to examine the shared vari- 
able’s state vector. The state vector indicates 
which of you has set a value of which the other 
is still ignorant. It also shows which of you is 
aware of the shared variable’s current value. 


The state vector 


The function (SVS gives you the state of each of 
the variables named in its argument. 


In general, the result is a 4-column matrix, con- 
taining on each row the state vector for the corre- 
sponding name in the argument. When you in- 
quire about a single variable and use a scalar or 
vector argument to do so, the result is a 4-element 
vector. 


The first two elements: who has set a value that 
the other hasn’t used? The first two elements 
of the state vector indicate which processor has set 
a value of the shared variable that has not been 
used by the other. The first element refers to 


“ ”» 


you,” and the second to “your partner.” 


The partner who has set a value that remains 
unused is indicated by a 1. A 1 can occur as one 
of those elements when that partner was the last 
to set the shared variable and the other partner 
hasn’t used it. There’s no way the first two ele- 
ments could both be 1. However, they could both 
be 0. When both partners are aware of the shared 
variable’s value, neither of them can have set a 
value of which the other is unaware, and so the 
first two elements are both 0 0. The first two 
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elements are also 0 0 when sharing has just been 
established, and neither processor has yet set the 
shared variable. 


The last two elements: who’s aware? The last 
two elements of the state vector indicate which of 
the partners is aware of the shared variable’s cur- 
rent value. The third element refers to “you,” and 
the fourth to “your partner.” 


The partner who last set a value for the shared 
variable must be aware of it (having just set it!). 
The other partner can be aware of the shared 
variable’s value only if it has used it since the time 
it was set. Thus, the last two elements may be 
either one 1 or two 1s. 








Four possible states 


















Who has set Who knows 
a value that the current 
the other value? 


hasn’t used? 


Your Your 








POSSIBLE VALUES OF DSVS AND THEIR INTERPRETATION 


partner You partner 


When sharing has just been established, it is pre- 
sumed that neither processor has yet set a value 
for the shared variable, but that each knew what 
value the variable had in their respective work- 
spaces before it was shared. 


Possible states: During active sharing, only 
three distinct states of [SVS are possible. (The 
fourth state is all zeros, indicating that the name 
is not shared.) 


You might think that a 4-element vector is a rath- 
er extravagant way to represent a system with only 
four possible states. That representation was cho- 
sen because it corresponds to the one used for the 
access control vector. 


SN 





Interpretation 








You and your partner are both aware of the 
current value, and neither has since set (and 
initial value when sharing first established). 










You’ve set the shared variable, but your partner 
hasn’t used it. 


Your partner has set the shared variable, but you 
haven’t used it. 


The name isn’t the name of a shared variable. 
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Access control 


Either of the partners may assure effective com- 
munication between them by setting the appro- 
priate elements of the access control vector. 


The goal in synchronizing communication is to 
inhibit the partner who is about to set a new 
value from doing so too soon (before the other has 
had a chance to use the former value), and to 
inhibit the partner who is using the variable from 
doing so too soon (before the other has had a 
chance to provide the data to be used). The access 
control vector allows the system to enforce the ap- 
propriate delays. 


Like its state vector, a shared variable’s access con- 
trol is a 4-element Boolean vector. By making the 
appropriate elements 1, either partner may speci- 
fy that certain actions will be inhibited. You set 
the access control vector by using the dyadic func- 
tion SVC. Before either partner has set it, its 
value is 0 0 0 O. 


You can’t set a name’s access control until after 
you have offered to share it. If you attempt to do 
so, the result is the access control as it was, un- 
changed. 


The right argument of [SVC is the name of a 
shared variable, and the left argument is the 4- 
element vector indicating which actions you 
propose to inhibit. Alternatively, the right argu- 
ment may be a matrix of names, in which case the 
left argument is either a corresponding matrix of 
4-element vectors, or a single vector which applies 
to all of them. 


A shared variable’s access control vector has four 
elements with significance as follows: 


Inhibit Set 


Inhibit Use 


Your Partner You Your Partner 





Wherever a variable’s access control vector con- 
tains a 1, the corresponding action is inhibited. 
The effect of a 1 in each of the four positions is 
as follows: 


1 You are inhibited from setting a new value 
for the shared variable until after an inter- 
vening use (or set) by your partner. 


2 Your partner is inhibited from setting a new 
value for the shared variable until you’ve 
done an intervening use (or set). 


3 You are inhibited from using the value of 
the shared variable until after an interven- 
ing set by your partner. 


4 Your partner is inhibited from using the 
value of the shared variable until after an 
intervening set by you. 


Effective access control: The system keeps 
track of the access control vector proposed by each 
partner for each variable. The result of each use 
of SVC is the effective access vector. It is cal- 
culated by OR-ing together the access control vec- 
tors proposed by each of the partners. 


Because the effective access control is obtained by 
the logical function OR, either partner is free to 
insert a 1 in any of the four positions (that is, to 
inhibit any of the four possible actions). However, 
one partner cannot change to 0 any element that 
the other set to 1. That is, you can always increase 
the level of inhibition for yourself or your partner, 
but you can remove only those inhibitions which 
you set. 


State of the shared variables 


In most circumstances, communication is con- 
sidered effective only if each partner receives 
everything sent by the other exactly once (neither 
missing anything nor receiving spurious du- 
plicates). An effective transmission is thus one that 
changes the state vector from one of its three possi- 
ble settings to another. 
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There are two ways an action could leave the state 2. If one of the partners were to use the shared 
vector unchanged: variable twice in a row (before the other partner 
could supply new information). Those are the si- 
tuations that are potentially misleading. For this 


1. If one of the partners were to set the shared reason, each 1 in the access control vector inhibits 
variable twice in a row (before the other partner an action which would leave the state vector 
could use the earlier value). unchanged. 













Csvs TRANSITION TABLE: 
NEW STATE FOLLOWING EACH OF FOUR POSSIBLE ACTIONS 
TAKEN IN EACH OF THE THREE POSSIBLE VALUES OF [SVS 


Nee 


Possible actions and state following each 












Preceding state You set Partner sets You use Partner uses 


an 










0 0 1 1 You both have used 1010 0101 * x 
(and initial state) 


1 0 14 0 You have set 


0 10 1 Your partner has set 1010 * 0011 x 






An action marked « would produce no change to DSVS, and is inhibited while either partner maintains 
a 1 in the corresponding position of the access control vector. When sharing is first established, 
OSVS iso 0 1 1. 


The information in the figures is represented graphically in Figure 16 of APL Language, IBM 
publication GC26-3847-4. In that publication, the state vector and the access control vector are depicted 
as 2-by-2 matrices. 
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OSVS TRANSITION DIAGRAM: 
PATH TO NEW STATE FOLLOWING EACH OF FOUR POSSIBLE ACTIONS 
FROM EACH OF THE THREE POSSIBLE VALUES OF OsSvs 


You both have used 
(and initial state) 


0 0 1 


* * 
Partner || You Partner 
sets use uses 


You have set 


Partner|| You Partner 
sets use uses 


An action marked by * would produce no change in (SVS, and is inhibited while either partner 
maintains a 1 in the corresponding position of the access control vector. 
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Attempting to carry out an action that is in- 
hibited: Suppose you have a variable whose 
state vector at present contains 1 0 1 0 (“You’ve 
set”) and whose control vector has a 1 as its first 
element (“Inhibit me from setting until after my 
partner has used”). You attempt to give it a new 
value anyway. What happens? You experience a 
delay. There is no interrupt or error message, but 
the system waits to make your specification until 
your partner uses (or sets) the variable. The delay 
lasts indefinitely—as long as it takes. You can’t do 
other work, but the CPU costs for the delay are 
negligible. 


From the terminal of a T-task, you can signal an 
interrupt (two successive uses of the ATTN or 
BREAK key). This aborts your attempt to use the 
shared variable. The system displays the error 
message INTERRUPT, and displays the statement 
it was attempting to execute. 


A similar delay will occur if a variable’s state 
vector has a 1 in the third position (meaning that 
you know what the variable’s value is), and 
there’s a 1 in the third element of the variable’s 
access control (meaning “Inhibit me from using 
until after my partner has set”). There’s an indef- 
inite delay until your partner has again set a value 
for the shared variable. As before, you can’t do 
other work, but the delay has negligible CPU cost. 
You can interrupt the attempt to use the inter- 
locked variable by signalling an interrupt. 


Watch out: While you’re trying to discover what 
went wrong with a program that has been inter- 
rupted by an error, it may seem natural to attempt 
to display a shared variable. But such a display 


counts as a use of the variable, and might be in- 
hibited. 


If you wish to be able to make repeated references . 


to the value of an interlocked shared variable, the 
best technique is to immediately assign its value 
to another (non-shared) variable, so that you can 
refer to it as often as need be, without making a 
new reference to the shared variable. 


Note on DPACK, 4 [WS and 6 OWS applied to a 
shared variable: When you use the name of a 
shared variable in the argument of any of those 


_s 


three functions, as far as the shared variable 
processor is concerned, that does not constitute a 
use of the shared variable. With OPACK and 
6 DWS you get the last value visible in your work- 
space, and with 4 [WS you get the size of the last 
value visible in your workspace. Thus, you only 
get a value that you already know (either because 
you’ve already made some other use of it, or 
because you’re the one who set it). Using any of 
those three functions has no effect on the shared 
variable state. 


Calculating in advance which actions will not 
be delayed: By examining a variable’s state vec- 
tor and its access control vector, you can tell which 
actions will not be subject to delay. Recall the four 
possible actions: you set, your partner sets, you 
use, and your partner uses. For a variable X, an 
action you're free to take immediately (that is, 
with no delay) is any of those indicated by a 1 
in the expression 


(OSVS 'X')aQsve 'X' 


Notice that if your partner has set a value for the 
shared variable, you aren’t obliged to use it even 
when the variable is fully interlocked. You could 
go ahead and set a new value yourself. In most 
circumstances, that would be foolish, but you 
might want deliberately to signal your partner that 
you no longer want to use what the partner is 
transmitting. This is symmetric: when you’ve set 
the shared variable, your partner isn’t obliged to 
use the value you’ve set either, but always has the 
option to set the variable again. 


Meaning of some possible settings of a vari- 
able’s access control vector: The following 
examples illustrate the effect of some possible set- 
tings of a shared variable’s control vector. 


0000 No interlock. Such a setting is rea- 
sonable only when you know that 
there are other constraints that 
will prevent the two processors 
from getting out of step. This 
might happen if the programs 
which use this shared variable 
without interlocks also make use of 
another variable that is inter- 
locked. 
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Neither of us can set a new value 
until the other has used it. (Some- 
times called half duplex.) 


Neither of us can use the shared 
variable until the other has set it. 
(Sometimes called half duplex.) 


You can’t set until your partner 
has used, and your partner can’t 
use until you’ve set. (Sometimes 
called simplex transmission from 
you to your partner.) 


You can’t use until your partner 
has set, and your partner can’t set 
until you’ve used. (Sometimes cal- 
led simplex transmission from 
your partner to you.) 


Full interlock: reversing -half du- 
plex. 


State-change signal 


Suppose you have a function that uses several 
shared variables (for example, an N-task that 
serves several users at once). The function may, 
on occasion, reach a point where it has nothing to 
do immediately, but is waiting for a reply to come 
in from any of its several shared variables. 


In that situation, you can have the function wait 
(without CPU cost) until something happens that 
may require its attention. You do that by referring 
to the system variable DSC. 


DSC is a variable that is automatically shared with 
the system. Whenever you use DSC, you get the 
value that the system has set. That value is either 
0 or 1. The interesting thing about [JSC is usually 
not what its value is, but when you get it. While 
you are using shared variables, between any two 
successive uses of SC, the system must have de- 
tected a state change. If there hasn’t been a state 
change, execution is delayed until there is one. 


State change: A state change is any change in 
the result of OSVS for any variable you’re now 
sharing, or any new offer to share, or any retrac- 
tion of a variable already shared. 


Once your active workspace has established a valid 
clone ID, each time a state change occurs, the 
system sets the value of JSC to 1. You cannot use 
that value more than once; when you next refer 
to OSC, the value you get will be a value that the 
system set after it set the value you used previous- 
ly, and therefore indicating that there has been at 
least one state change since you last used OSC. 
Thus the value of 0SC—when you succeed in 
referring to it—is always 1. 


Whenever your workspace lacks a valid clone ID, 
the value of DSC is 0, and is delivered immediately. 


If there has been a state change since you started 
sharing or since the last time you referred to 
OSC, you get that value 1. But if there hasn’t been 
a state change, the system doesn’t return the value 
of DSC until there’s been a state change. Hence, 
referring to OSC amounts to waiting indefinitely 
(at no CPU cost) until some state change takes 
place. However, if someone retracts an offer that 
was made to you but which you have not accepted, 
that doesn’t count as a state change. 


A reasonable sequence for using [JSC is: 


1. Using OSVS, verify that there’s nothing you can 
do at present with the relevant shared variables. 


2. Use SC in an expression such as 
+(QSC/LABEL) ,ERROR 


Provided you have a valid clone ID, that will 
delay the branch to LABEL until some state change 
occurs. But if you lack a valid clone ID (and so 
can’t possibly be making effective use of shared 
variables), control will pass immediately to 
ERROR. 


3. When you’ve received a 1 from OSC, use 
OSVS or DSVQ to review the situation and decide 
what action is possible or appropriate. 


Retraction 


The function (SVR retracts your offer to share 
each of the variables named in its right argument. 
This cancels sharing of any variables for which 
sharing was in effect, or aborts the offer to share 
those that the intended partner hasn’t yet accepted. 
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The result is a vector indicating the level of cou- 
pling of each of the variables at the time that you 
withdrew the offer. 


Illustrative programs for an N-task with multi- 
ple users 


The following definition is intended to illustrate 
how you might set up an N-task or B-task capable 
of accepting share offers, and handling work in 
rotation from each of the various sharers, each 
running at its own pace. 

















[3] CHECK: WORK 

[4] OLDOFFERS 

[5] +NEWOFFERS/CHECK 
[6] DWELL: >))SC/CHECK 








V 






[2] TEST: >(0epCHANGED)+tO 












V 





y OLDOFFERS; OK; J 





[3] SHV ARS+OK 4SHV ARS 
IDS+*OK/IDS 










[2] TEST: +(0=1tpNEWIDS)+0 




























Y MONITOR CLONEID; SHVARS; IDS; SERIAL 
[1] SHVARS+ 0 0 pIDS+ 0 2 pSERIAL+0 
[2] CLONEID4])SVN CLONEID 


[7] 'CLONE ID NOT ESTABLISHED! QSIGNAL 555 


The subroutines called by MONITOR are: 


V WORK; CHANGED; SHVAR 
[1] CHANGED<( (DSVS SHVARS)[;1+010])/11tpSHVARS 


[3] @SHVAR,'+ PROCESS ' , SHV AR-SHVARS[ ' 'oCHANGED; ] 
C4) CHANGED+1+CHANGED 
[5] >TEST 


[1] >+(A/OK+2=0SVO SHVARS)+0 
[2] JEX(~OK)#SHVARS a RETRACTS SHARE AND ERASES NAME IN WS 


Y Z*NEWOFFERS; J; ID; NEWIDS; NEWNAMES; SURROG 
[1] +(O0¢pNEWIDS<DSVQ '')tZ+0 O Z<1 


aAPPENDS NEW IDS AND NAMES TO GLOBALS <IDS> AND <SHVARS> 


In an application such as this, it is common for 
each of the T-task workspaces which shares with 
the “monitor” to offer the same name. Suppose 
each offers to share X. In order to distinguish the 
various names, for each X offered to it, the monitor 
must construct a unique internal name. One 
scheme for constructing names is to include in the 
internal name the processor ID of the workspace 
making the offer. For example, when the monitor 
receives from processor 7844919 5 an offer to 
share X, the reply uses OSVO with a right argu- 


3] NEWNAMES<ID NAMEFN SURROG<]SVQ ID«NEWIDS(OIO; J 
C4) J+(((1+tpNEWNAMES) ,2)pID) QSVO NEWNAMES,' ',SURROG 
[5] J+ 1114 1 OSVC NEWNAMES 

[6] SHVARS*«SHVARS ON NEWNAMES 

EZ] IDS-IDS,[DIO]((1tpNEWNAMES),2)pID 

[8] NEWIDS+« 1 0 +NEWIDS 

[3] +TEST 
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ment which includes X as the surrogate name 
paired with an internal name, perhaps as follows: 


(1 297844919 5) QSVO 'X000784491900000000500001 X' 


A function NAMEFN could generate unique names 
in such a fashion: 


V  Z*IDS NAMEFN NAMES; N 


[1] N<''ppNAMES<«(-+/A\ONAMES=' ')QNAMES 


[2] IDS«(N,2)pIDS 


[3] Z«NAMES ,'ZI10, ZI9, ZI5' QFMT IDS,100000|SERIAL+1N 


[4] Ze(Zt.=" ')O2 
[5] SERIAL<SERIAL+N 


[6] A SERIAL IS USED TO DISTINGUISH OFFERS OF SAME NAME FROM SAME USER 


V 


Storage space for the value of a shared variable 


A value that your partner has set isn’t visible in 
your active workspace until you refer to it. It’s 
possible for your partner to give the shared vari- 
able a value that requires so much storage space 
that (although it fits in your partner’s workspace) 
there isn’t room in your workspace to receive it. 
If that happens, at the moment that you attempt 
to refer to its value, the system interrupts work 
and displays the error message WS FULL. 


Saving a workspace that contains shared vari- 
ables: When a workspace is saved, the value of 
each of its variables must be physically present 
within it. When you give the command )SAVE or 
)CONTINUE, the system first moves into the work- 
space the current value of each of the shared vari- 
ables which you haven’t yet used. 


If it proves impossible to transfer the value of a 
shared variable because there isn’t space, the 
system displays the error message WS FULL, and 
does not save the workspace. 


Following a bounce or line-drop, the system 
executes )CONTINUE on your behalf. If there isn’t 
sufficient space to bring in the values of all of your 
shared variables, the system saves the workspace 
anyway, with as many of the values as it can 


accommodate. 
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Chapter 12: 


THE SHARP APL 
FILE SYSTEM 





THE SHARP APL FILE SYSTEM 


The SHARP APL file system gives you a way to 
store data in a form directly usable by APL, but 
outside any workspace. It also permits you to use 
data stored by others (for example, public data 
bases), or to share with other users access to a 
common collection of data. Auxiliary storage out- 
side of workspaces is organized into files. A set 
of system functions deals with the file system. 
These file functions give you means to create and 
manage such auxiliary storage, and means to 
transfer data between it and the active workspace. 


Library number of a file 


Like a workspace, a file has both a user account 
with which it is associated and a name. The name 
may have up to eleven alphanumeric characters, 
and must start with an alphabetic character; it 
can’t contain a blank, a period, or any other 
symbol. 7844919 DATA is the full name of a file 
called DATA belonging to user 7844919. 


Ownership of a file 


The owner of a file is the person who gets the bill 
for storing it. The owner also has some implied 
powers over the file. For a file in a private library, 
the owner is the person identified by the library 
number. Alternatively, a file may be part of a 
public library (having a number less than 1000). 
In that case, its owner is the person whose task 
caused the file to be in that public library, either 
by creating it with that library as part of its name, 
or by subsequently renaming it to have that li- 
brary number. 


Structure of a file 
Each file is organized into components. You trans- 


fer data between a file and the active workspace 
one component at a time. The components of a file 


are arranged in sequence. Each component is iden- 
tified by its position in the sequence. When you 
request to transfer the data in a particular com- 
ponent of a file, you have to indicate the number 
of the file component to which you’re referring. 


When a file is created, its first component is com- 
ponent 1. That is true regardless of the index 
origin of the workspace that’s using the file. It is 
possible to drop components either from the begin- 
ning or from the end of a file. Once some compon- 
ents have been dropped from the beginning of a 
file, its first component will no longer be compon- 
ent 1. 


Form of data storage in a file component 


Each data object in a file component is self-des- 
cribing. That is, its rank, shape, and type are 
stored with it. The various components of a file 
may differ in the amount of space that they oc- 
cupy, and in rank, shape, and type. 


Each component of a file is a single APL data 
object—that is, either a rectangular array, or a 
package. The object stored in a component of a file 
does not have a name. For example, if you transfer 
an array called X from the active workspace to a 
file component, everything about that array in the 
workspace (including its rank, shape, type, and 
value) is transferred to the file, but not the name 
X. When you subsequently transfer that compon- 
ent back to the workspace, you may use it directly 
in an expression without naming it, or you may 
assign a name to it. In either case, the file compon- 
ent does not itself contain any indication of the 
former name. i 


Control information in each file component 


Each component of a file includes a record of the 
number of the account that wrote it, together with 
the date and time at which it was written. The 
way in which this control information can be read 
and decoded is explained in the definition of 
ORDCI. 


The fact that each component is individually 
timestamped is important in maintaining the inte- 
grity of data storage. It permits the system utilities 


to detect, on a daily basis, which components have 
been newly written, and to make back-up copies 
of those records without having to make reserve 
copies of everything in the system. This makes it 
feasible to maintain daily backups even though it 
would be impractical to save copies of the entire 
file system that frequently. 


Space reservations for files 


The size of a file is measured in bytes. It takes 
one byte to store a single character, four bytes to 
store an integer, or 8 bytes to store a floating point 
number. The number of bytes a file occupies is the 
number required for the data itself, plus a certain 
overhead required for the data description and for 
tables that the system uses to locate components 
within the file. The total amount of space a file 
occupies may also vary depending on the sequence 
in which you replace the contents of some compon- 
ents. For example, if you replace the array stored 
in one component with another array that takes 
more space, it might be some time until the system 
is able to re-use the space that was vacated. For 
a while, the file will occupy more space than it 
would if you’d written all of the components in 
sequence. 


The “lumpiness” of a file is corrected during a 
periodic system maintenance of files. (At the LP. 
Sharp Toronto Centre, this is done each week- 
end.) Thus, at the beginning of a new week, it 
is possible to find that a file requires less storage 
space than it did at the end of the previous week. 


When a file is created, you specify a limit on the 
size to which the file may grow (see the definition 
of (CREATE). The limit is called the file reserva- 
tion. Reserving space for a file doesn’t consume 
that space until you use it, and you aren’t charged 
for it unless you use it. What the reservation does 
is set a limit beyond which the system will not 
accept new entries; this serves primarily to protect 
you from inadvertently using more storage than 
you had intended. Once you’ve reached a file’s 
limit, the system rejects a statement that would 
require additional space with the message 
FILE FULL. 
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When the actual number of bytes used in a file 
exceeds the file’s reservation, you can’t append any 
new components, or replace an existing component 
by a larger one. But up to that point, the system 
will always accept a new component, even if it 
won't fit within the reservation limit. 


When a file reaches its reservation limit, you may 
decide to increase the limit. That’s called resizing 
the file. You can increase a file’s reservation and 
resume work. Resizing a file is a relatively expen- 
sive operation, so it is prudent to anticipate how 
much a file is likely to grow, to avoid having to 
resize it frequently. Note that storage charges are 
based on space actually used, rather than on max- 
imum space reserved, so resizing a file to a size 
greater than you use does not itself influence stor- 
age charges. 


Limit on total of file reservations 


For each account, the system managers set a limit 
on the sum of outstanding reservations that its 
owner can make. This is the sum of the reserva- 
tions for each file you own, regardless of the li- 
brary they’re stored in, and regardless of whether 
they’re actually used. If you reach this limit, you 
will be unable to create a new file (unless it’s 
empty), or to resize an existing file to make it 
larger. To increase the reservation quota for your 
account, contact the system Operator or your 
SHARP APL representative. 


Identifying which file you’re talking about 


Each time you use a file function that refers to a 
specific file, you have to include in its argument 
something that identifies which file you mean. You 
do that by including in the function’s argument a 
tie number. The tie number is an arbitrary in- 
teger. During each task (that is, T-task, N-task, 
or B-task) before you do anything else with the 
file, you first link the file’s name to a number. 
That’s called tying the file. Thereafter you use the 
tie number as part of the argument of each func- 
tion in which you refer to that file. 


Reference to an existing file is thus a two-stage 
process: 
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1. To start using an existing file, you tie it (using 
the function [TIE or QSTIE). You thereby link 
the name of the file to some integer. The integer 
must be one that’s not already tied to a file. 


2. Thereafter, each function that refers to the file 
uses the file’s tie number as part of its argument. 


If you’re not authorized to make any use of a file, 
the system won’t let you tie it, and so you won't 
be able to use any file function in a way that 
would refer to that file. 


If you create a new file, you specify a tie number 
at the time; the act of creating it share-ties it to 
that number. 


Duration of a file tie 


Once you’ve tied it, a file remains tied until you 
untie it using the function QUNTIE, or until the 
end of the task, whichever occurs sooner. 


A file tie is not affected by changes to the active 
workspace; in particular, it’s unaffected by such 
actions as clearing the active workspace, or loading 
another saved workspace into the active area. In 
that regard, a file tie is like a session variable, and 
unlike the duration of a shared variable. 


A file tie does not continue into another task. 
Moreover, the system doesn’t supply the new task 
any record of what files were tied in the parent 
task, or what numbers were used to tie them. 


Watch out: A task started by splitting the active 
workspace appears in many ways identical to the 
active workspace of its parent—but does not in- 
herit the parent’s file ties, shared variables, or ses- 
sion variables. 


When a task is terminated prematurely (for exam- 
ple, by an error in an N-task or B-task, or by a 
communications failure in a T-task), the system 
saves the active workspace. You may subsequently 
reload it to continue work or to find out what went 
wrong. But when it saves a workspace, the system 
doesn’t do anything to show what files were tied 
or what numbers were used to tie them. If you 
think you'll need that information, you should 
have your program keep some record of it in the 
active workspace. 


Control of access to a file 


For each file, the system maintains an access ma- 
trix. The access matrix stipulates three things con- 
cerning access to a file: 


1. Account number. Who may tie the file. 


2. Permission code. What functions you’re per- 
mitted to use with the file once it’s tied. 


3. Passnumber. A number you must supply when 
tying the file, and each time you use a file function 
with it as long as it’s tied. 


A passnumber is an arbitrary integer which 
(when the access matrix requires it) you must 
supply both when you tie the file and each time 
you use any of the file functions with this file. 
That number serves as a password, except that it’s 
a number rather than an array of characters. You 
will sometimes hear numeric passwords informally 
referred to as “magic numbers.” 


Format of the access matrix 


The access matrix is a 3-column matrix of in- 
tegers. Its columns have the following significance: 


1. User ID: The account number of a person 
who has the right to use the file. 


If this number is 0, it means “anybody.” 


2. Permission code: A number indicating 
which file functions can be used by the person 
identified in column 1. 


Each individual permission code is a power of 2. 
Any combination of permissions can be expressed 
as the sum of their separate distinct permission 
codes. (But note when you sum them that the 
permission codes you add together must be dis- 
tinct; adding two identical permission codes will 
give something different from what you intended. ) 


If the permission code is ~1, it means access is 
granted to all file functions. (That’s because the 
binary representation of ~1 is all 1’s.) 


There’s a list of permission codes accompanying 
the discussion of ORDAC and DSTAC. 


w 


3. Passnumber: A number which the user must 
supply as part of the argument in order to tie the 
file, and as part of the argument of each file func- 
tion used with the file. 


Passnumber 0 is equivalent to “no passnumber.” 
In that situation, you can either use a file function 
with no passnumber in its argument, or with the 
passnumber 0. 


If you’re not the owner of a file, you have no 
powers to make any use of it’ except as granted 
in the access matrix. 


If you are the owner of a file, you may do any- 
thing with it unless the access matrix assigns you 
a more restrictive permission. 


When a file is first created, its access matrix is 
empty. That means that the file’s owner may use 
any of the file functions with a passnumber of 0 
(or no explicitly stated password), but no one else 
may use any of them. 


The owner of a newly created file has the power 
to add new rows to the access matrix. Those new 
rows may grant to others any of the possible per- 
missions (including the right to amend the access 
matrix itself). The owner’s account retains the 
power to do anything with a file until its number 
appears explicitly in the access matrix. Then, 
whatever access is explicitly granted overrides the 
owner’s general access. 


The owner of a file in a public library is the 
account which put it into that library (when it 
was created, or when it was subsequently re- 
named). 


Effect of permission codes on use of file func- 
tions 


You can use one of the system functions for work 
with files only if you have permission to use it. 
Permission means permission to use a specific 
function (or functions) with a specific file. With 
the description of each of the file functions, you'll 
find the permission code for that function. That 
permission must be in effect for the particular file 
with which you want to use the function. 
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You'll need explicit permission to use a particular 
function with a particular file if either of the fol- 
lowing is true: 


1. You aren’t the file’s owner. 


2. The file’s access matrix explicitly includes your 
account number with a zero passnumber, even 
though you are the owner. 


Use of passnumbers 


If you use a passnumber (other than 0) to tie a 
file, then you must also use it with every file func- 
tion you use with that file. The only exceptions 
are the functions (UNTIE, OCREATE, and QHOLD, 
which never take a passnumber. 


Passnumbers are provided for security. If you have 
an application which requires access to sensitive 
data, you should arrange to have all access to the 
file provided by a locked function. The locked 
function should include the passnumber as a con- 
stant which is never assigned to any variable. That 
















1. Define the following: 










1 and O in column 3. 





. Is there a row which c 








If YES, it’s OK to tie; go to step 6. 


If NO, continue to step 4. 
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How the system selects a permission code from the access matrix 
a A EE 


USER Account number of user requesting to tie the file 
OWNER Account number of user whose task created the file, or last renamed it 
PASSNO Passnumber supplied with request to tie, or 0 if none was supplied 


2. Append to the bottom of the access matrix one additional row containing OWNER, 1 0. 


This unstated extra row permits the owner to tie the file without a passnumber, and to use 


any file function, unless the access matrix already contains a row with OWNER in column 


ontains both USER in column 1 and PASSNO in column 3? 


locked function can make certain tests before it 
supplies the needed number; the tests might in- 
clude posing a question to the user at the terminal, 
or checking the date or time at which access is 
requested, the node from which the user is signed 
on, and so on. The actual access should follow the 
test, but on the same line as the test, so that even 
if the function is interrupted, the line can never 
be re-executed without executing the test. 


Rules governing access matrices 


Each time you attempt to tie a file, the system 
consults that file’s access matrix to see whether 
you're permitted to tie the file, and if so, what 
you’re permitted to do. When your request to tie 
a file is accepted, the system selects a permission 
code from one row of the access matrix. If the 
matrix contains only one row that applies to you, 
the choice is simple. But when there are several 
rows that might apply, it helps to understand the 
rules by which the system picks one of them. 


. Is there a row containing 0 (anyone) in column 1 and PASSWO in column 3? 


If YES, it’s OK to tie; go to step 6. 


If NO, the file cannot be tied. 


- Report FILE ACCESS ERROR and quit. 


. OK to tie: Permission code is column 


(starting from the top). 


2 of the first row on which a match was found 


Once the file is tied, access is limited to the function or functions described by the permission 
code. Each access will require both the tie number and the passnumber supplied in the 
request (but passnumber 0 is equivalent to no passnumber). 


The following states the preceding rules as an APL function: 


V PeMATRIX GETPERMISSION X; Q; USER; OWNER; PASSNO; QIO 
[1] QIO+1 © USER+X[1] © OWNER-X[2] © PASSNO<X[3] 


[2] MATRIX+MATRIX,[1] OWNER, “1 0 


[3] >(V/Q+MATRIX[ 31 3]A.=USER,PASSNO)+0OK 


[4] >(V/Q-MATRIX[;1 3]a.= 


[6] OK: P4MATRIX[Q11;2] 
V 


Once it has selected a permission code, based on 
the access matrix, the owner, the user, and the 
passnumber supplied with the request to tie, the 
system makes a record of the permission code it 
calculated and the passnumber you used. If the 
access matrix is changed while you’re using the 
file, the changes take effect immediately. With 
each use of any of those functions with respect to 
this file, you must include the passnumber you 
used when you tied it. 


Using a passnumber (other than 0) when none 
is required is just as inappropriate as failing to use 
one when it is required. 


It’s possible for you as owner to set up the access 
matrix of your file so that there are certain things 
you can’t do with it yourself. It’s also possible to 
give to others the ability to do anything with your 





0,PASSNO)+OK 
[5] 'FILE ACCESS ERROR' © +P+0 


file—even to change its access matrix, or to re- 
name it so that that person becomes the file’s 
owner. 


Your use of the file is controlled by the access 
matrix as it currently is. If the access matrix is 
changed while you’re using the file—even if you're 
the one who changes it—that immediately affects 
both the permission code and the passnumber. The 
passnumber with which you tied the file could 
thus become obsolete even while you’re using it. 


Watch out: It’s possible to alter a file’s access 
matrix in such a way that it becomes impossible 
to do anything useful with it. If you prevent your- 
self from tying a file to which you should have 
access, or from revising the access matrix appro- 
priately, your only recourse may be to request the 
assistance of the system Operator (for example, by 
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sending a message with the )OPR command). 
After verifying that you are the owner of the file 
and are entitled to access to it, the system Operator 
may arrange to temporarily override the access 
matrix, permitting you to reset it to a more reason- 
able value. 


The file system is independent of the APL in- 
terpreter 


The SHARP APL file system is, strictly speaking, 
a processor that is independent of the APL inter- 
peter. In all normal operations, both are running 
at the same time. But there are a few occasions 
when the APL interpreter may be running while 
the file system is not running. This could occur 
during the initial few minutes when the system is 
being started after shutdown, or following recovery 
from a system crash. When such a situation arises, 
all but one of the file functions are unable to 
operate, and instead return the error message 
FILE SYSTEM UNAVAILABLE. The sole exception 
is the function DAVAIL. It is provided solely to 
permit you (if you wish) to check whether the file 
system is running. It is prudent to include such 
a check as an initial step in a program that will 
run automatically (for example, as an N-task that 
is started by an automatic profile or by a latent 


expression ). Wey 
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Chapter 13: 


AUTOMATIC 
TRAPPING OF 
ERRORS AND 
INTERRUPTS 





SHARP APL provides ways in which you can 
state in advance what you want the system to do 
when execution in your active workspace encoun- 
ters an error or an interruption. The system may 
then respond automatically to an event which oth- 
erwise would have caused work to be halted. 


Trapping events: An interrupt or error which 
can be intercepted is referred to as a trappable 
event. The term “event” is deliberately vague, 
partly to reflect the wide variety of things it covers, 
and partly to allow for the possibility that, in the 
future, the category may be expanded. It might 
then include some events that are neither errors 
nor interrupts, and do not halt execution. 


When you provide an alternate instruction to be 
executed if a certain event occurs, you are said to 
trap that event. The SHARP APL event-trapping 
facility consists of the system variables DER and 
OTRAP, and the system function DSIGWAL. 


Some situations in which event trapping is use- 
ful: It’s useful to trap an error if (a) it doesn’t 
happen every time, and (b) you’re fairly certain 
of being able to provide a remedy when it does 
happen. In a situation like that, to verify in ad- 
vance that no error will occur may be more dif- 
ficult or more expensive than simply to let it hap- 
pen and then correct it when it does. For example, 
if you’re writing data to a file, there’s a risk that 
there won’t be room in the file to receive the next 
value. One approach would be to check in ad- 
vance, each time you write a component, to see 
how much space is available and how much is 
required by your new data. Alternatively, you 
could set [TRAP so that if the file is full, some 
remedial action is taken (resizing it, repacking it, 
starting another, as appropriate). That way your 
program wouldn’t need to check in advance. 


A more striking (if specialized) example arises 
when you use matrix inversion. Some matrices are 
singular (have no inverse) and are rejected with 
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the message DOMAIN ERROR when they’re used in 
the right argument of §. But to verify in advance 
that a matrix has an inverse is more expensive 
than matrix inversion. Using DTRAP, you could 
specify an action to be taken only if E has been 
attempted and has failed. 


Without (7RAP, an application that accepts input 
from a user—especially from a user unsophisticat- 
ed in programming—might require elaborate 
checking to verify that what the user has typed is 
acceptable. This, too, can be avoided by setting 
OTRAP to catch the errors that may arise, and then 
simply accepting input. 


To make an application secure, you may want to 
prevent a user from interrupting some functions, 
so that the person at the keyboard has no oppor- 
tunity to return to immediate execution and 
examine data that the function uses, files that are 
tied, and so on. By setting OTRAP appropriately, 
during critical segments of the program you can 
intercept the user’s signals of “attention” or “in- 
terrupt,” or use of O BACKSPACE U BACK- 
SPACE T so that the person has no possibility of 
returning to immediate execution mode until 
you're ready to permit it. 


Some events can’t be trapped: There’s no pro- 
vision to trap certain types of interruption. For 
example, a task can’t trap a signal to bounce it. 
Some messages that you may receive at a terminal 
report events that aren’t trappable. For example, 
you can’t trap the trouble reports that arise from 
problems with a system command. And messages 
sent by the system’s input processor, transmission 
control, or communications network—for example, 
LINES DOWN or CHAR ERROR or PATIENCE 
PLEASE—are completely outside the workspace, 
and not trappable. The chapter entitled “Error 
Messages and Trouble Reports” indicates which 
messages accompany events that can be trapped. 


Outline of the trapping facilities 


Event report: When any interrupt or error oc- 
curs, the system stores as the value of DER, a char- 
acter matrix containing a description of the event. 
The description includes the error message that 
may also be displayed at the terminal. 


Trap definitions: The variable [TRAP is used to 
indicate what events you want to trap, and what 
you want done when they occur. The system ex- 
pects [TRAP to be a character array, containing 
any number of trap definitions. Each trap defini- 
tion is a list of events (identified by number), 
together with the action to be executed when one 
of them occurs. 


Whenever an interrupt or error is detected, the 
system searches through the values of OTRAP for 
mention of the type of event that has occurred, 
and, if it finds one, carries out the action specified 
there. 


User-defined errors: The function QSIGNAL 
permits a user-defined function to abort its own 
execution and generate an error signal, in much 
the same way that the system may abort execution 
of a primitive function and report an error. 


How interruptions are handled when you are 
NOT trapping them 


While the system is executing a line of APL 
(whether it’s a line just entered from the keyboard 
or a line within a defined function), work may be 
interrupted for any of a variety of reasons. When 
that happens, unless you’ve used [TRAP to provide 
otherwise, execution halts. If you’re working from 
a terminal, following most events, the system dis- 
plays an error message. (Regardless of whether 
you're using []PRAP, if the event is one that could 
be trapped, the message that’s displayed is also 
included in the value of DER.) Then the system 
waits for you to enter from the keyboard an in- 
struction telling it what to do next. 


If you’re running an N-task or a B-task, there’s 
no way to receive an error message and no way 
to indicate what should be done next. Work simply 
stops. The system saves the task’s active work- 
space. 


While you’re working at a terminal, your response 
to an interruption may often (although not al- 
ways) include the following three steps: 


1. Decide why the event occurred, by examining 
the message the system displayed, and perhaps by 
performing other tests. 
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2. Take necessary steps. 


3. Resume work. If you were executing a defined 
function, you usually resume work by entering a 
branch statement such as +LABEL or ~OLc. 


The instruction you store in DTRAP will often 
(although not always) provide the same three 
kinds of activity. 


Event reporting 


Event numbers: To indicate which events you 
want to trap, and to identify an event when 
examining DER, each kind of event has an event 
number. When the system puts into [ER a des- 
cription of the last error or interrupt, it always 
devotes the first four characters of the top row to 
the event number. 


OER describes the most recent trappable inter- 
rupt or error: Following an error (whether an 
error detected by the system itself, or one generat- 
ed by use of QSIGNAL), or an interrupt, the 
system generates an event report. (Event 2001, 
return to immediate execution, is trappable but is 
neither an error nor an interrupt, and isn’t record- 


ed in DER.) 


The system assigns the event report as the value 
of the system variable DER. DER is a variable that 
the system sets, but you use. After an error or 
interrupt you may consult [ER to decide on an 
appropriate action; similarly, the instruction you 
write in TRAP may also consult [ERP to select an 
appropriate remedial action. 


Like any variable, DER may be made local to a 
function. When the name DER has been localized, 
the QER that receives the event report is the one 
that is visible; that is, the most local one. 


When the system specifies a new value for DER, 
any previous value of that DER is replaced by the 
new one. However, any more-global [ER 
(shadowed by the local meaning) remains unaf- 
fected. 


Since DER is a variable, you could, if you wanted, 
assign to it any value you like—but doing so 
would be pointless and possibly confusing. The 





system makes no use of QER other than assigning 
to it the latest event report each time a reportable 
event occurs. 


Form of DER: A value of DER set by the system 
is always a character three-row matrix. In a clear 
workspace in which no trappable event has oc- 
curred, ER has shape 3 0. When the system sets 
a value for (JER, it always includes the event num- 
ber. If the workspace lacks space for a complete 
event report, the system makes DER a one-by-four 
matrix containing only the event number. 


Event number: The first four elements of the 
first row of QER always contain the character re- 
presentation of the event number, right-justified. 


Suppose that while executing a function called 
REPORT, the system finds that a variable named 
TOTAL has no value. Here’s how [ER would ap- 
pear: 


6 VALUE ERROR 
REPORT[3] DISPLAY+ITEMS BESIDE TOTAL 
A 


SN 


Statement being executed 


er, 
Fn. name 
& line no. 


Caret points where system was working 


Following the event number, DER usually contains 
a description of the event. The three rows of 
DER are used as follows: 


1. Title (describing the event) 


2. Statement (reproduced from the line being 
executed ) 


3. Caret (pointing to part of the statement) 
When the event described in DER occurred during 


execution of a locked function, the system with- 
holds some of the information that would other- 
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wise be included. Row 2 of DER contains the func- 
tion name and row number, followed by the char- 
acter ¥. The caret on row 3 points to the ¥ symbol. 


When the workspace lacks space to contain a com- 
plete DER, the system uses a terse form which 
contains only the four characters of the event num- 
ber, as a one-by-four matrix. 


Event title: Provided the workspace is not too 
full, following the event number, the first row of 
DER contains one blank and then the event title. 
When the event was one recognized by the system, 
the system selects its title from its stock of standard 
phrases, such as SYNTAX ERROR, WS FULL, and so 
on. An event report generated by dyadic 
[SIGNAL contains, instead, whatever title was 
specified in the left argument of OSIGNAL. 


Statement reproduced: The second row of DER 
reproduces the statement that was being executed 
when the event occurred. When that statement was 
part of a defined function, the function’s name and 
the line number (in brackets), appear at the start 
of the second row. When the function was locked, 
the statement is replaced by the single character 
7. 


When the event was an error generated by 
(SIGNAL, the second row shows the statement that 
invoked the function whose execution was aborted 
by DSIGNAL. 


Caret: The third row of DER contains a number 
of blanks and a single a (“caret”). The position 
of the caret indicates where, within the statement 
reproduced on the second row of DER, the system 
was working at the moment the event occurred. 


Default display: For almost all events, the mes- 
sage the system displays when you are not using 
OTRAP has the same appearance as DER. However, 
in a default display, the system does not show the 
event number. For certain events (for example, 
halt before a line marked by a stop vector) the 
system doesn’t display a title, but starts immediate- 
ly with what’s on the second row of DER. 


Classifying events to simplify trapping them 


To make it simpler to specify which events you 
want to trap, events are divided into three classes: 


1. Error: An error arises whenever the system 
finds that it cannot execute the line it is currently 
working on. An error may reflect an ill-formed 
statement (SYNTAX ERROR) or an inappropriate 
use of data (DOMAIN ERROR, RANK ERROR, 
LENGTH ERROR, INDEX ERROR). 


An error may also arise when there is nothing 
wrong with the statement itself, but other condi- 
tions are not met. Lack of a needed object may 
cause VALUE ERROR; lack of space may give rise 
to WS FULL ERROR or FILE FULL, and so on. 


Some error messages—such as NO SHARES or 
PILE SYSTEM NOT AVAILABLE—reflect a state 
of affairs over which you may have no direct con- 
trol. 


User-defined errors: Within a defined function, 
you can decide to abort execution and report an 
error, using the function DSIGNAL. Doing so halts 
execution of the statement that invoked the defined 
function, in much the same way as the system 
halts execution of a statement when it can’t 
execute a primitive function. 


When you cause a defined function to report an 
error, you may either report one of the errors that 
the system recognizes (such as SYNTAX ERROR, 
DOMAIN ERROR, etc.), or you may arbitrarily de- 
signate error conditions of your own. 


Event number of an error: An error detected 
by the system has an event number in the range 
1 to 499. To an arbitrary error report, signalled 
by OSIGNAL from within a defined function, you 
may assign any event number from 1 to 999. 
However, since the system uses numbers up to 
499, it’s prudent to confine user-generated errors 
to numbers in the range 500 to 999. 


When you’re specifying which events are to be 
intercepted by (TRAP, event number 0 is under- 
stood to mean “any error”—that is, any event 
whose number is in the range 1 to 999. 


2. Interrupt: An interrupt is a signal which 
causes execution to be halted. In general, an inter- 
rupt is a signal received from outside the work- 
space. For example, signalling “attention” or “in- 
terrupt” while a function is being executed (by 
one or by two successive uses of the ATTN or 
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BREAK key), or signalling “interrupt” during 
input (by typing O BACKSPACE U BACK- 
SPACE 1), is an interrupt. 


A halt to execution caused by the way the STOP 
control (SA) is set is also considered an interrupt. 


An interrupt is classified by what the system was 
doing at the time it occurred. Suppose you signal 
an interrupt from the terminal (by two successive 
uses of ATTN or BREAK). When the activity 
you interrupted was use of a shared variable, the 
System reports that as event 1005 SY 
INTERRUPT. But when the activity you interrupt- 
ed was a file access, the system reports it as event 
1006 FILE INTERRUPT. 


Any of the current set of trappable interrupts can 
arise only from intervention by a user at a termin- 
al (using the ATTN or BREAK key), or from 
the setting of the STOP control. The system func- 
tion QSIGNAL cannot generate an interrupt. 


Each interrupt has an event number in the range 
1001 to 1999. When you’re stating which events 
are to be intercepted by ỌTRAP, event number 
1000 is understood to mean “any interrupt.” 


3. Return to immediate execution: Return to 
immediate execution is not an error or interrupt 
in the usual sense, and does not cause the system 
to set MER, but is trappable. You can include, in 
a trap definition, provision to take certain actions 
if, for any reason, the workspace returns to im- 
mediate execution mode. 


There’s a return to immediate execution whenever 
the system completes execution of the last APL 
line entered from the keyboard (or when it com- 
pletes execution of DLX after loading a work- 
space). There’s also a return to immediate execu- 
tion following any error or any interrupt which 
is not successfully handled by (TRAP. 


When you’re stating what events are to be inter- 
cepted by TRAP, the event number 2001 is under- 
stood to mean “any return to immediate execu- 
tion.” Following return to immediate execution, 
the possible actions are (1) to do nothing; (2) to 
clear the workspace; or (3) to exit (see the des- 
cription of action D). Trapping return to im- 
mediate execution serves primarily as a conven- 





ience at the normal end of an N-task or B-task, 
or as a security measure, to be invoked where 
other mechanisms have failed. 


List of trappable events: The table shows the 
event number the system assigns to each of the 
events it recognizes. A user-defined function using 
OSIGNWAL can evoke any of the errors (having 
numbers between 1 and 499) or a user-defined 
error (having a number between 500 and 999). 
The list also includes the event numbers 0 and 
1000, which are never directly reported by the 
system, but which, when they appear in a trap 
definition’s list of event numbers, serve as short- 
hand for a class of events. 







Errors 


Within a trap definition, serves to trap any 
error. 

WS FULL 

SYNTAX ERROR 
INDEX ERROR 

RANK ERROR 
LENGTH ERROR 
VALUE ERROR 
FORMAT ERROR 

11 DOMAIN ERROR 

15 SYMBOL TABLE FULL 
16 NONCE ERROR 

18 FILE TIE ERROR 

19 FILE ACCESS ERROR 
20 FILE INDEX ERROR 
21 FILE FULL 

22 FILE NAME ERROR 
23 FILE DAMAGED 





1 
2 
3 
4 
5 
6 


N 


24 FILE TIED 
© 


26 FILE SYSTEM ERROR 


O 28 FILE SYSTEM NOT AVAILABLE 


30 FILE SYSTEM TIES USED UP 
31 FILE TIE QUOTA USED UP 

32 FILE QUOTA USED UP 

33 FILE RESERVATION ERROR 

34 FILE SYSTEM NO SPACE 

38 FILE COMPONENT DAMAGED 

45 WS LOCKED 

46 WS NOT FOUND 

47 WS NOT READABLE 

72 INTERFACE QUOTA EXHAUSTED 
73 NO SHARES 

INTERFACE CAPACITY EXCEEDED 
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75 SHARE TABLE FULL 
76 PROCESSOR TABLE FULL 
77 IDENTIFICATION IN USE 
78 OPP ERROR 
79 [PW ERROR 
80 [T0 ERROR 
81 URL ERROR 
82 DCT ERROR 
83 [DHT ERROR 






Interrupts 





1000 Within a trap definition, serves to trap any 
interrupt. 

1001 STOP 

1002 ATTENTION 

1003 INTERRUPT 

1004 INPUT INTERRUPT 

1005 SV INTERRUPT 

1006 FILE INTERRUPT 

1007 FILE BACKUP INTERRUPT 








Return to immediate execution 
——— 


2001 Within a trap definition, serves to trap any 
return to immediate execution. 


Events that are reported but not trappable 


There are two error conditions which cause the 
active workspace to be cleared. The system dis- 
plays the message SWAP ERROR, CLEAR WS or 
SYSTEM ERROR, CLEAR WS. Following these, the 
system sets [ER to show event 67 for 
SWAP ERROR and event 68 for SYSTEM ERROR. 
Since the active workspace is cleared, they couldn’t 
possibly be trapped. They may be useful in under- 
standing the fate of an N-task or B-task which is 
interrupted by one of these errors, since (unless 
the workspace was cleared with CLEAROUT or by 
trap definition 2001 D CLEAR) the system saves 
its active workspace with DEF in it. 


The form of DTRAP 


Each [TRAP may contain any number of trap 
definitions. When a trappable event occurs, the 
system searches through the various trap defini- 
tions until it finds one that applies to the event. 








(TRAP may be either a matrix or a vector. When 
it’s a matrix, each row contains a trap definition. 


When [IRAP is a vector, the system treats the first 
character as a delimiter which serves to separate 
the various trap definitions. Since the individual 
trap definitions will often contain APL statements 
to be executed, it’s convenient and customary to 
use, as delimiter, a character that you’re sure 
won’t appear in any of the APL statements that 
the various trap definitions may include. In the 
examples that follow, the character V is used as 
the delimiter, but any of several other characters 
would be equally appropriate. 


The following example illustrates the two forms, 
matrix and vector. The content of the two is 
equivalent. 


Matrix DTRAP: 


oLITRAP 
14 
OTRAP 
28 E >WAIT 
18 24 C >RETIE 


Vector DTRAP: 


pLITRAP 
29 
OTRAP 
VY 28 E -WAIT V 18 24 C +RETIE 


Form of a trap definition: Each trap definition 
contains at least two fields, and optionally, a 
third. The three possible fields are: 


1. Event numbers: Lists (by number) the 
events to which the trap definition applies. 


2. Action code: A single letter, separated from 
the adjacent fields by blanks. 


3. Trap line or keyword (optional after certain 
actions): Instructs the.system what it should do 
following the event, and (optionally) how execu- 
tion should be resumed. 
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Below appears a possible trap definition to illus- 
trate the various components just mentioned: 


Action 
code Trap line 


ere 


V 4 5 11 C DATA<QER REDO DATA © +RESUME 


Ç 


Delimiter Blanks 
(vector OTRAP only) (around action code) 


In the preceding example, the trap line contains 
two statements. The first respecifies the value of 
a variable DATA by invoking a function REDO, 
which refers both to the existing value of DATA 
and to DER. The second instructs the system to 
resume execution by branching to RESUME. 


System requires well-formed [TRAP: [TRAP is 
a variable you share with the system. Ordinarily, 
you set [RAP and the system uses the value 
you've set. However, when you assign a value to 
UTRAP, the system requires that it be a well- 
formed set of trap definitions. If the value you 
propose contains a trap definition that is not well- 
formed, the system sets a new value for DTRAP, 
and makes it an empty vector. For example, you 
might observe the following sequence: 


OTRAP+' JUNK! 
pOTRAP 
0 


Criteria for a well-formed OTRAP: A well- 
formed [TRAP is one in which each trap definition 
is well-formed. 


1. Each trap definition starts with the character 
representation of a non-empty list of event num- 
bers. 


2. Following the list of event numbers, and separ- 
ated from it by at least one blank, each trap defini- 
tion must contain one of the action codes 
CEN S D. 





3. Following action code C or E, a trap definition 
may have a trap line. If there is a trap line, it 
must be separated from the action code by at least 
one blank. 


Following action code D, there may be a keyword, 
which may be either CLEAR or EXIT. If there is 
a keyword, it must be separated from the action 
code by at least one blank. 


Watch out: A frequent error in preparing a vec- 
tor DTRAP is omitting the delimiting character. A 
delimiting character is required at the start of each 
definition, even when ỌTRAP contains only one 
definition. 


A well-formed [TRAP isn’t necessarily valid: 
After you set a value for TRAP, it’s prudent to 
examine it, to see whether the system has accepted 
it, or has reset it to an empty vector because it 
wasn’t well-formed. But the fact that the system 
accepts a [TRAP as well-formed doesn’t mean that 
the trap definitions it contains will work, or will 
do what you want. It means only that [TRAP is 
in acceptable form. When the system accepts a 
OTRAP as well-formed, it doesn’t check the con- 
tents of each definition’s trap line. An error in the 
trap line will become apparent when the system 
attempts to make use of it—that is, when it inter- 
cepts an error and attempts to execute the trap 
line. An error in the trap line is not trappable. 


How the system locates the relevant trap defin- 
ition 


As soon as any trappable event occurs, the system 
halts work on the statement it was executing, and 
starts searching through the various trap defini- 
tions. If one doesn’t cover the event that has just 
occurred, it goes on to the next trap definition. 


Within a single value of QTRAP, it considers the 
various trap definitions one after another. When 
OTRAP is a matrix, it considers the trap definitions 
in sequence from top to bottom. When [TRAP is 
a vector with trap definitions separated by a 
delimiting character, it considers them in sequence 
from left to right. 


As soon as the system finds a trap definition whose 
list of event numbers includes the event that has 


AUTOMATIC TRAPPING OF ERRORS AND INTERRUPTS 112 





just occurred, it searches no further, and proceeds 
to carry out the action prescribed by the trap 
definition. 


Search through multiple levels of O7RAP when 
OTRAP is localized: The variable (TRAP may be 
made local to a function. While that function is 
active, the local value of DTRAP is visible, and any 
other values of [TRAP outside the function are 
shadowed. You cannot see a shadowed value of 
OTRAP. But the system can! 


While searching for a relevant trap definition, the 
system considers first the local, visible value of 
OTRAP. But if it doesn’t find a match there, it goes 
on to consider each of the shadowed values as well. 
In this regard, the system’s treatment of shadowed 
values of DTRAP is quite different from its treat- 
ment of shadowing in most other situations. (The 
system function 5 [WS can show you at what 
levels of the state indicator TRAP is localized. ) 
For all other purposes, a shadowed value is simply 
invisible. But when the system is searching for a 
trap definition, when the visible value of OTRAP 
doesn’t contain a relevant trap definition, it contin- 
ues its search with the next shadowed QTRAP. If 
need be, it continues through all values of DTRAP 
that may exist at any level of localization. 


Consequences of the way the system treats 
shadowed values of DTRAP 


1. When you use a function with a local (TRAP, 
any event not covered in its trap definitions is 
governed by whatever trap definitions may exist 
in more global values of DTRAP (if any). 


2. As long as a DTRAP exists, each of its trap 
definitions remains in effect except while a more 
local (7RAP covers the same event. 


3. It’s always possible to write a function so that 
trap definitions in its local OTRAP supersede any 
other trap definitions. 


Watch out: You might think that by localizing 
(TRAP and making it empty, or failing to give it 
a value (so that there is no visible DTRAP), you'd 
interrupt event trapping. Not so. If your local 
OPRAP doesn’t cover an event, the system simply 
looks at the next more global OTRAP—which you 





can’t see but it can. Notice that your failure to 
specify a value for a local QTRAP has a con- 
sequence quite different from failing to specify the 
value of any other localized system variable, such 
as DZO or OPW. If you left one of those undefined 
but used a statement that required it, the system 
would signal a message such as [IO ERROR, 
OPW ERROR, etc., as appropriate. 


Possible actions in the trap definition 


Following the field containing the list of event 
numbers, each trap definition has a second field 
containing an action code. The action code must 
be separated from the event numbers by at least 
one blank. 


Following certain actions, there may be a third 
field. When the third field appears, it must be 
separated from the action code by at least one 
blank. The third field may be a trap line (option- 
al with action C or E), or a keyword (optional 
with action D). 


Each action is represented by a single letter. The 
five possible actions are: 


evnums C [line] CUT 
evnums £ [line] EXECUTE 
evnums 1 NEXT 


evnums S STOP 
evnums D [keyword] DO 


Event numbers: The first field of any trap defi- 
nition is a list of the event numbers to which it 
applies (shown in the examples as evnums). The 
list of event numbers contains one or more num- 
bers, in any order. Each number is represented 
using the characters 0 through 9. Representations 
of the various numbers in a list must be separated 


by blanks. 


evnums C line Cut back and execute trap 
line 


When the system detects an event whose number 
is included in evnums, it aborts the execution of 
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all functions invoked later than the function to 
which the relevant ỌTRAP is local. (Note: A 
function that was invoked later appears higher on 
the state indicator.) 


Every function started later than the function to 
which the relevant QTRAP is local, is aborted. 
That’s true regardless of whether the function was 
pendent or was suspended. 


The system removes the names of the aborted 
functions from the upper rows of the state indica- 
tor. At the same time it removes their line num- 
bers from the leading components of OLC. This 
removal from the state indicator and from DIC is 
referred to as “cutting back the state indicator”; 
hence the code “c.” 


After the system has cut back the state indicator, 
it sets the new value of DER. Then it executes the 
trap line (if any). The trap line may contain any 
number of statements, separated by diamonds. Its 
total length may not exceed 500 characters, not 
counting leading or trailing blanks. 


If the trap line contains an error, the system halts; 
an error in a statement contained directly in the 
trap definition can’t itself be trapped. However, 
when the trap statement invokes a defined function 
or uses ¢ to evaluate a character vector, errors in 
that function, or in the argument of ¢, are trap- 
pable in the usual way. 


Branch with action C: When the trap line in- 
cludes a branch statement, the system resumes 
execution of the function in which the relevant 
LITRAP was localized (which, since the state in- 
dicator has been cut back, is now its top line). 


The system understands the value that appears to 
the right of > in the branch statement to be a 
reference to a line or label in the function now at 
the top of the state indicator, just as it would if 
execution were halted and the branch statement 
were entered directly from the keyboard. Note that 
the trap line does not show on the state indicator, 
and is not represented in DZC, so there’s no need 
to allow for it when you state the destination of 
the branch. 


Watch out: When you specify a trap definition 
that contains action C (and especially if action C 
is combined with a branch) be sure that the func- 
tion which sets QTRAP also includes [TRAP in its 
header as a local variable. 


evnums Z line Execute trap line 


When the system detects an event whose number 
is included in evnums, it immediately sets a new 
value for DER. Then it executes the trap line (if 
any). The trap line may contain several statements 
separated by diamonds. However, its total length 
may not exceed 500 characters, not counting lead- 
ing or trailing blanks. 


If the trap line contains an error, the system halts; 
an error in a statement contained directly in the 
trap definition can’t itself be trapped. However, 
when the trap statement invokes a defined function 
or uses ¢ to evaluate a character vector, errors in 
that function, or in the argument of ¢, are trap- 
pable in the usual way. 


Branch with action Æ: When the trap line in- 
cludes a branch statement, the system resumes 
execution of the function it was working on, at the 
line indicated. A branch statement appearing in a 
trap definition is executed exactly as if it had been 
entered from the keyboard. Note that the trap line 
does not show on the state indicator, and is not 
represented in DZC, so there’s no need to allow for 
it when you state the destination of the branch. 


Watch out: When the statement following action 
E contains a branch, the system branches to the 
indicated line of the function on which it was 
working when the event occurred. That may 
not be the function which set D7RAP, but another 
function invoked subsequently. About the only 
branch whose effect is certain with action E is 
*ULC—and even that assumes that any function 
whose execution may be halted can safely be re- 
started on any line. If you want to branch to a line 
other than the line on which the system was work- 
ing when the event occurred, it is much more pru- 
dent to use action C rather than E. 
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evnums Ų Skip to next level 

When the system detects an event whose number 
is a member of evnums, it abandons the search 
for trap definitions in the QTRAP at which it is 
now looking. Then it moves to the next level at 
which DTRAP is localized, and continues its search. 


What happens after action N is what would hap- 
pen if the [TRAP simply made no mention of those 
events. Action N is useful primarily when com- 
bined with the event numbers 0 or 1000. For 
example, a DTRAP containing the two trap defini- 
tions 


OTRAP«'V 2 14 N V 0 E CORRECTION' 


has the effect of saying, “For all errors except 2 
and 14, execute CORRECTION.” 


evnums S Stop 


When the system detects an event whose number 
is a member of evnums, it halts work and displays 
an error message, in the same way that it does 
when you don’t use event trapping. It returns to 
immediate execution. 


In effect, action S turns off the automatic handling 
of events. It is useful primarily during debugging, 
to prevent the system from attempting to deal au- 
tomatically with errors other than those you an- 
ticipate, or to exclude certain errors from a general 
trap definition, for example: 


OTRAP«+'V 2 14 S V 0 E CORRECTION' 


evnums D keyword Do 


Action D is available only with event number 
2001; conversely, event 2001 can be followed only 
by action D. Hence, 2001 is the only event number 
that may appear in the trap definition for action 


In a trap definition, the event number 2001 stands 
for any return to immediate execution. That does 
not include [| input mode. 


When the system detects a return to immediate 
execution, it checks to see whether there is a trap 
definition for event 2001. There might have been 
a return to immediate execution because a function 
invoked from the keyboard (or by [ZX) has 
reached a normal end. Or it might be because 
work has been halted following an error or an 
interrupt for which there is no trap definition, or 
for which the trap definition doesn’t include a 
branch statement. 


When the system returns to immediate execution 
following an interrupt or error, the system first 
displays whatever message is called for. Then (if 
it has returned to immediate execution) it checks 
whether there’s a trap definition for event 2001. 
If there is, it acts on the keyword that follows 
action code D in the trap definition. 


Note that because the system handles the error or 
interrupt first, and then checks 2001, you might 
see it display an error message which mentions a 
particular function, but by the time the keyboard 
is returned to you, that function may no longer 
exist on the state indicator. 


Normal end of execution: When the system 
reaches a normal end of a function that was in- 
voked from the keyboard (or by automatic execu- 
tion of (LX), first it exits from the function, and 
then it checks for a trap on event 2001. A trap 
for 2001 that was local to the function from which 
the system just exited will by then no longer exist. 
Hence, a local trap definition containing action D 
can apply only to a halt other than a normal end. 


Effect of keywords with action D: When the 
system finds a trap definition for event 2001, what 
it does next is determined by the keyword appear- 
ing to the right of D. The keyword may be empty, 
or may be CLEAR or EXIT. 
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Effect of empty keyword: When the keyword 
is empty, the system returns to immediate execu- 
tion in the usual way. 


Effect of keyword EXIT: The system aborts 
execution of the most recently invoked function 
(the one at the top of the state indicator). If that 
function was invoked during use of [Q or 2, it 
aborts the J or ¢ as well. It cuts back the state 
indicator until the top row refers to a defined 
function (rather than to [J or 2). At the same time, 
it makes a similar adjustment to DZC. 


To the function now at the top of the state indica- 
tor, the system again signals event 2001. The new 
2001 is treated according to the provision for event 
2001 in whatever []TRAPs remain after the state 
indicator has been cut back. 


When the trap definition 2001 D EXIT to which 
the system was responding was one it found in a 
QOTRAP local to the function just aborted, that 
[TRAP no longer exists; the system searches anew 
for a trap definition for event 2001. If it finds one, 
it acts on it. If it doesn’t find one, it returns to 
immediate execution. 


The sequence “abort the current function, and 
again signal event 2001” is repeated indefinitely 
until the system finds that it has no definition for 
event 2001, or a definition with an empty key- 
word. 


If at each level the system continues to find 
2001 D EXIT, the effect is equivalent to 
)RESET . In that case, the system returns to imme- 
diate execution with the state indicator empty, but 
with no effect on global functions or variables. 


Effect of keyword CLEAR: The workspace is 
cleared, as it would be if you’d entered the com- 
mand )CLEAR from the keyboard. You may want 
to do this either as a rather Draconian security 
measure, or as a convenience to prevent the system 
from saving the active workspace following normal 
end of an N-task or B-task. 


Watch out: If you want to clear the workspace 
only at the normal end of-a job (so that the work- 
space of an N-task or B-task is saved only if it’s 
interrupted), the trap definition 2001 D CLEAR 
should appear only in the global value of 
OPRAP; as long as the function is active, the global 
value should be superseded by a local [TRAP con- 
taining a trap definition 2001 D (without the key- 
word CLEAR). 


The trap definition 2001 D CLEAR replaces the 
function CLEAROUT in workspace 1 WSFNS, which 
is now considered obsolete. However, CLEAROUT 
and its companion NOCLEAR still work. 


CLEAROUT takes precedence over all event trap- 
ping: Before the introduction of event trapping, 
the functions CLEAROUT and NOCLEAR in work- 
space 1 WSFNS provided a service similar to that 
now provided by the trap definition 
2001 D CLEAR. The former facility is now con- 
sidered obsolete, but still works on the SHARP 
APL system. However, in a workspace in which 
CLEAROUT has been set, (TRAP is completely 
inoperative. Instead, any error or interrupt causes 
the system to clear the workspace. 


Events that can’t be trapped 


Certain errors and interrupts can’t be trapped. 
They are the following: 


1. An error encountered while executing the line 
that is part of the trap definition. An error in the 
trap line is exempt from trapping, primarily to 
avoid endless recursions that might otherwise arise 
from a defective trap line. 


However, an error in a function invoked by the 
trap line, or in the argument of ¢, can be trapped 
in the usual way. 


A function invoked by the trap line but aborted 
by OSIGNAL can also be trapped. In that case, 
[ER reproduces the trap statement. 
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Paaa 


2. An interrupt caused by DBOUNCE. When a task 
is “bounced,” provided CLEAROUT has not been 
set, its active workspace is saved. DER in the saved 
workspace will show one of the interrupts. Which 
one depends on the circumstances when the task 
was bounced. 


3. Any of the following errors is considered an 
error in transmitting or setting up the line for 
execution, rather than an error in execution. None 
of them causes DER to be set. None of them has 
an event number. 


OPEN QUOTE ERROR The line 
balanced quotes. 


contains un- 


CHAR ERROR The line as received from the ter- 
minal contains an unrecognizable character. The 
system displays the characters preceding the first 
offending character, and awaits a corrected entry. 


WS FULL ERROR There is insufficient space to 
prepare the line for execution. Note: This mes- 
sage is distinct from event 1 WS FULL, which in- 
dicates that there isn’t space to complete execution 
of the line. 


SYMBOL TABLE FULL ERROR There is insuffi- 
cient space in the symbol table to prepare the line 
for execution. Note: This message is distinct 
from event 15 SYMBOL TABLE FULL, which in- 
dicates that the symbol table lacks space to accom- 
modate names generated during execution of the 
line. 


DEFN ERROR The line contains an improper use 
of the V character. 


Signalling a user-defined error 


Using DSIGNAL, you can make a defined function 
abort its own execution and report an error event, 
much as the system does when it cannot complete 
execution of a primitive. You can trap that event 
in the usual way. When the system finds no trap 
for such an event, it displays the event’s standard 
title (if there is one), or the title provided as 
(ISIGNAL’s optional left argument. 


Each use of (SIGNAL (whether from within a 
defined function or entered from the keyboard) 
aborts execution of the function at the top of the 
state indicator. The right argument provides the 
event number to be signalled. It can be any num- 
ber greater than 0 but less than 1000—usually one 
for which the system has no standard meaning. 


While debugging, it’s convenient to enter from the 
keyboard SIGNAL followed by an event number 
for which no trap has been set. That aborts execu- 
tion of the halted function and restarts the state- 
ment that invoked it. 


Building and testing functions that use event 
trapping 


While automatic handling of errors or interrupts 
offers many advantages, there are ways in which 
it complicates the task of developing a new ap- 
plication. 


If you’re used to using APL without event trap- 
ping, you’re likely to assume that when anything 
goes wrong, the system will halt with an error 
message, and you can decide then what steps to 
take next. You may assume that if work isn’t pro- 
ceeding as you like, you can always halt it by 
signalling an interrupt, and then take remedial 
action. But once you set TRAP, an error may 
produce new behaviour, bypassing the messages on 
which you previously relied, and resuming execu- 
tion without halting at all. The situation may be 
even more perilous if you use [TRAP to intercept 
interrupts signalled from the terminal. You may 
find it impossible to interfere with a function’s 
execution; you may find that setting a stop vector 
(with SA) no longer has the expected effect. Of 
course, it is precisely to produce such invulnerabil- 
ity that you may wish to trap errors. The risk is 
that doing it incorrectly may produce some very 
inconvenient behaviour. 


Suggested precautions: When you use event 
trapping, you may need to plan and test your 
programs with a thoroughness and caution that 
would not be needed without DTRAP. The follow- 
ing are some rules of thumb that may be useful. 
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1. Test the trap line by entering it from the 
keyboard. The trap line which accompanies ac- 
lions C or E is executed in the same way as if work 
halted and you entered it from the keyboard. You 
can exploit this fact when you’re building a new 
application. Start with trap definitions which in- 
clude the event number and action code E or C, 
but which provide no trap line, or a trap line 
consisting solely of QER. 


During a trial run of your function, when the 
event is intercepted, the system will halt and will 
return control to you at the keyboard. That will 
permit you to look around before committing your- 
self to the next step. When you have settled on a 
sequence of statements which, when entered from 
the keyboard, produce the behaviour you want, 
make them the trap line of your trap definition. 


2. Include a trace capability as part of a tenta- 
tive trap definition. For example, while testing 
a new [J?RAP, you might include in each trap line 
a reference to TRACE, so that a trap definition 
might look like this: 


evnums E£ TRACE (JER } FIXUP © >RESUME 


In that example, FIXUP and +RESUME are state- 
ments you expect to remain in the final version, 
but TRACE is included solely for testing. You can 
easily have TRACE report the circumstances in 
which the trap was invoked, or have it halt (with 
a local O7RAP of its own) so that you regain con- 
trol. 


3. Provide default trap definitions for events 
not otherwise covered in (TRAP. If you make 
DTRAP local to a function you’re building, but fail 
to specify trap definitions for some events, you are 
in effect letting a more global OTRAP (if there is 
one) decide what will happen when one of those 
events occurs. Until you’re really ready to do that, 
it would be prudent to append to your (TRAP a 
definition such as 0 1000 S (meaning “Stop after 


— 


any error or any interrupt”). That will assure a 
halt for any event you haven’t anticipated. 


4. When testing a function with a local 
OTRAP, establish a default [7RAP outside it. 
When a trappable event occurs during execution 
of a function with a local TRAP, the system first 
examines the local [TRAP, and, if that doesn’t 
cover the event, looks next at the global [7RAP in 
effect when the function was invoked. Until your 
function is behaving satisfactorily, make sure that 
the global [TRAP will handle unexpected events. 
The simplest way to do that is to make the global 
OTRAP’s first trap definition something such as 
0 1000 S. 


5. Use DSIGNAL to test error conditions that 
may not otherwise arise conveniently. You may 
have included a trap for an event that occurs only 
rarely and is inconvenient to arrange. You can test 
the working of the trap by using SIGNAL to gen- 
erate a report of the error you wish to trap. 
Because (SIGNAL aborts execution of the function 
that used it, it is usually preferable to embed it 
in a defined function such as ERRSIGNAL: 


V ERRSIGNAL N;DTRAP 
[1]  OfRAP+'o 1000 S$! 
[2] DSIGNAL N 

v 


You could then invoke the test conditionally, by 
inserting a reference to it at the start of the line 
where you anticipate an error: 


MAINFN[..] ERRSIGNAL C/evnums © WORK 


In the foregoing, evnums are the events to be 
trapped, and C, the condition under which they are 
to be trapped; WORK represents the normal contents 
of the line. 


6. Consider a trap definition that resets 
OTRAP. A trap definition may include, in a trial 
version of its trap line, an instruction which resets 
OTRAP to something that will prevent the original 
QTRAP from being inadvertently invoked again. 
For example, a trap definition might be as follows: 
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evnums Z [7RAP«'VO 1000 S' © FIXUP © +RESUME 


After the first use of this DTRAP, a subsequent 
error will encounter the new value of DTRAP, and 
work will stop. 


7. Disable [TRAP in the workspace saved at 
halt of an N-task or B-task. When you design 
a workspace to be run in batch mode, there are 
several precautions to be observed. You want the 
latent expression to start the task correctly, but 
you want to avoid having the task start automa- 
tically at a terminal. 


Whenever a batch task halts, unless its active 
workspace was cleared, the system saves it under 
the savews name provided in the instruction that 
started it. If the task halted because of an error 
that wasn’t successfully trapped, you’ll want to 
load savews to find out what went wrong. Explor- 
ing a workspace in which [TRAP has been set can 
cause you some surprises; any error during your 
explorations may be trapped and may cause execu- 
tion to be resumed. To avoid that possibility, it’s 
good practice to set up the latent expression so that 
when you subsequently load savews, (a) execu- 
tion does not automatically resume, and (b) the 
visible value of ỌTRAP is saved (so that you can 
examine it) and immediately reset it to 
0 1000 S. 


The second precaution is included to assure that 
your efforts to examine the contents of the work- 
space are not trapped, and do not cause execution 
to be resumed. 


Other points regarding design of the latent expres- 
sion for a batch task are discussed in the manual 
“Batch Tasks in SHARP APL.” 


Special precautions when trapping interrupts: 
Writing a trap definition for interrupt events re- 
quires a great deal of caution. 


When a function behaves improperly, it’s impor- 
tant to be able to interrupt it. Whenever you set 
a trap for an interrupt, you are defining an alter- 
nate way for the system to respond to that inter- 
rupt, in place of its usual behaviour. You are 


thereby disabling (even if only temporarily) some 
of the built-in safety features of the system. For 
example, if you set up a trap definition which tells 
the system to resume execution following “atten- 
tion” or “interrupt,” as long as that trap definition 
is in effect, you have forfeited all ability to halt 
work by the usual signals you can send from the 
terminal (pressing ATTN or BREAK). 


When you set up a trap definition that intercepts 
an “input interrupt” (that is, 0 BACKSPACE U 
BACKSPACE T), you may find yourself with no 
means to escape from a request for character 
input. And if the program is in a loop, there may 
be nothing at all you can do to regain control. 


Warning: It is quite possible to write a defec- 
tive [TRAP that will make your program run 
endlessly, immune to most of the normal ways 
of halting it. That can be both annoying and 
expensive. If you make that mistake, the only 
recourse is to have your task bounced, or, if it’s 
a T-task, to disconnect the terminal. 


Responsibility to avoid prolonged unrespon- 
siveness: When you're using a high- 
performance interactive system such as SHARP 
APL, you have a right to expect that the system 
will execute your work promptly, and will respond 
promptly to emergency signals such as “attention” 
or “interrupt.” So do other people who may use 
programs you’ve written. There are situations in 
which it is clearly desirable to trap interrupts. 
Those are situations in which, either for security 
or for convenience, you don’t want the user to be 
able to interrupt a particular stage of the work. 
As author, you have a particular responsibility not 
to write programs that become unresponsive. 


Whenever the system seems no longer to heed sig- 
nals from the keyboard, any user should assume 
that something is wrong. It is normal to suspect 
that there has been a failure of the system itself 
or of the communication link between it and your 
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terminal. If you write a program that causes the 
terminal to become unresponsive for a significant 
interval—more than a second or two—you run the 
serious risk that you (or others who use your pro- 
gram) will be unable to distinguish that unrespon- 
siveness from a system failure. 


Whenever you use [TRAP to intercept inter- 
rupts, you have a serious responsibility: 


1. To keep the time during which interrupts 
are intercepted to an absolute minimum. 


2. To provide a substitute response (by trans- 
mitting a signal or message to the terminal) as 
part of your interrupt handling. That way, the 
person at the terminal has immediate confirmation 
that his or her signal has been received, even if 
it is not being handled in the usual manner. For 
example, a trap definition for interrupts from the 
terminal might read: 


1002 1003 1004 Æ ‘SIGNAL NOTED' ©} FIXUP ©} +RESUME 


dey 
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COMPARISON TOLERANCE 


How close is “equal”? The system variable OCT 
(for “comparison tolerance”) lets you specify the 
proportion by which two values may differ before 
the system judges them to be different. 


The issue arises because it may be necessary to 
compare two numbers when one of them is subject 
to an imprecision of computation or representation 
that may make it seem different from the other 
when it shouldn’t. 


The concept of comparison tolerance was in- 
troduced so that values that in principle are equal 
can be reported as “equal” by the system, despite 
small differences in how they are represented in- 
ternally. The system variable OCT specifies the 
proportion by which two values may differ and 
still be judged equal. (CT is sometimes informally 
referred to as “fuzz,” and functions subject to 
OCT are sometimes said to be “fuzzy.” 


Functions subject to DCT 


The following monadic functions are subject to the 
value of OCT: 


[Y 
LY 


And the following dyadic functions: 


X=Y 

XzYľ 

X<Y 

X<Y 

X2Y 

X>Y 

XeY 

XY 
o 
When the behaviour of a function is affected by 
OCT, it is always the visible (that is, most local) 
meaning of OCT which affects it. 


Meaningful values of (CT: The system will not 
prevent you from assigning to [CT any value you 
like. However, each time the system evaluates one 
of the functions involving comparison, it refers to 
the visible value of OCT, and requires that [ICT be 
a numeric scalar (or a 1-element vector) having 
a value not less than zero, but less than 16* 8, 
which is 2.328306437E 10. The upper limit on 
UCT serves to simplify the way the system com- 
pares integers by making it impossible for one 
integer ever to be reported “equal” to another. 


Comparisons without fuzz: For certain calcula- 
tions you may require exact comparison, without 
fuzz. You get that by setting OCT to zero. The 
dyadic functions X<Y and Xi1Y can be executed 
very much faster when [CT is 0. In a function 
which requires [C70 (or any other value differ- 
ent from the system-default value), you can make 
OCT local to that function. 


When [CT is zero, two numbers are judged equal 
if and only if their internal representations in the 
system are identical. For many purposes, that 
would be too strict a rule. Then you need a value 
of OCT that is still very small, but greater than 
0. 


Initial value of OCT: The global value of OCT 
in a clear workspace is 1.419697693F 14. 


In practice, it is rarely useful to set (CT to any- 
thing other than 0 or its default value. 


Application of [CT to dyadic functions: For 
all comparisons, the variable [JCT sets a relative 
tolerance. The system calculates the range of al- 
lowable deviation between two numbers you’re 
comparing by multiplying the visible value of 
OCT by the magnitude of whichever number has 
greater magnitude. As a consequence of this rule, 
OCT has no effect when one of the numbers being 
compared is zero. 


Formal definition of “equal” and “not equal” 


The English statement in the preceding paragraph 
can be represented by the definition of a function 
TEQ, which states explicitly how the system’s deci- 
sion “equal” or “not equal” is related to OCT: 


V ZX TEQ Y 
[1] AaTOLERANT EQUALITY 
[2] Ze(|X-Y) XLEQ OCTx(|X)F |Y 
v 


The foregoing definition makes use of XLEQ (for 
“exact less-than or equal”), a function in which 
OCT is localized and set to zero: 


V Z2+«X XLEQ Y; OCT 
[1] OCT+0o 
[2] ZeX<Y 

V 


Using the foregoing definition for tolerant equali- 
ty, tolerant inequality can be represented by the 
following definition: 


V 2Z«X TNEQ Y 
[1] Z<~X TEQ Y 
V 
Q 
Tolerant relations: Definitions for tolerant 
forms of the relations < < > > can be constructed. 
They make use of the definitions TEQ and XLEQ 
just presented, as well as the exact functions 
XLESS, XGRTR, and XGEQ, which are versions of 
< < 2 > in which QCT+0 in the same way that 
it was in XLEQ. The four definitions are then as 
follows: 


X<Y <> (X XLESS Y) A ~X TEQ Y 
X<Y +> (X XLEQ Y)v X TEQ Y 
X2Y <> (X XGEQ Y)v X TEQ Y 


X>Y <> (X XGRTR Y) A ~X TEQ Y 


Application of [CT to monadic functions 


The functions floor and ceiling represent a number 
by an integer; for an argument that is not an 
integer, floor “rounds down” to the next lower 
integer, while ceiling “rounds up.” However, if 
the argument is sufficiently close to an integer, 
that integer is returned as the result, regardless of 
the direction in which the argument differs from 
it. The amount of that tolerance is governed by 
pcr. 
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Informally, comparison tolerance affects floor and 
ceiling in the following way. A value that is exact- 
ly equal to an integer is unaffected: the result is 
that integer. A value that is close to an integer— 
that is, whose proportional departure from that 
integer does not exceed (CT—returns that integer 
as the result, regardless of the direction in which 
the value departs from the integer. All other values 
give the usual result; that is, LY returns the next 
smaller integer, while [Y returns the next larger 
integer. 


More formally, floor can be described by the fol- 
lowing definition, and then ceiling can be des- 
cribed in terms of it. In the definition, the value 
of DCT in the environment becomes the explicit 
argument CT. To find what this definition gives 
for the floor of Y when OCT has a particular value, 
you'd execute [CT FLOOR Y. 


V Z<CT FLOOR Y; OCT; NEAREST; ERROR; PERMISSIBLE 
[1] OicT+o 
[2] NEAREST+(xY)xL0O.5+/Y 
[3] ERROR<NEAREST-Y 
[4] PERMISSIBLE+CTx1I |Y 
[5] 2+NEAREST-ERROR>PERMISSIBLE 
y 


The ceiling of Y can be defined in terms of the 
floor and the value of OCT, as follows: 


OcT CEILING Y <> -OCT FLOOR -Y 


t% 
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Chapter 15: 


-MONADIC_ 
SCALAR 


FUNCTIONS 





Rank and shape of result: The result of a mo- 
nadic scalar function has the same rank and shape 
as the argument. 


+Y Conjugate of Y 
Argument: Any numeric array. 


Result: This function is included only for com- 
pleteness. At present it doesn’t really do anything. 
For some years there have been proposals that 
APL accept complex numbers. If it did, monadic 
+ would return the complex conjugate of Y. But 
at present, the system doesn’t support complex 
numbers, so the only numeric arguments you can 
supply are real. Hence, the result is identical to 
the argument. 


xY Signum of Y 


Argument: Any numeric array. 


Result: An integer array representing the sign 
of each element of Y as follows: 


Positive value 1 
Zero _0 
Negative value 1 


Signum is not affected by comparison tolerance. 
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-Y Algebraic negation of Y 
Argument: Any numeric array. 


Result: An array in which each element has the 
same magnitude as the corresponding element of 
the argument, but opposite sign. An element that 
has no sign—that is, whose value is zero—is un- 
changed in the result. 


+Y Reciprocal of Y 


Argument: Any numeric array in which no ele- 
ment is zero, or so small that its reciprocal would 
exceed the largest representable number. 


Result: An array in which each element is the 
reciprocal of the corresponding element of Y. 


xY Exponential of Y 


Argument: Any numeric array in which no ele- 
ment is so large that it would be impossible to 
represent the result (effectively, numbers less than 
about 174.6). 


Result: An array in which each element is e 
raised to the power Y (where e is the natural 


constant whose value is approximately 
2.718281828459045). 


@y Natural logarithm of Y 


Argument: Any numeric array in which each 
element is positive. 


Result: An array in which each element is the 
natural logarithm (that is, the log to the base e) 
of Y. 
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|Y Magnitude of Y 
Argument: Any numeric array. 


Result: An array identical to the argument, ex- 
cept that each negative element of the argument 
is made positive (so that all elements of the result 
are positive or zero). This function is also referred 
to as “absolute value.” 


'y Factorial of Y or Gamma function of 
Y+1 


Argument: Any numeric array in which no ele- 
ment is a negative integer, or so large (exceeding 
about 56), or so close to a negative integer, that 
the resulting value would be too large to represent. 


Result: When Y is a positive integer, !Y is the 
product of the natural numbers up to and includ- 
ing Y. The factorial of 0 is defined to be 1. 


When Y is a positive fraction, the Gamma function 
of Y+1 gives points smoothly interpolated between 
the factorials. 


When Y is a negative integer, !Y is undefined. 
Where Y is a negative fraction and LY is odd, !Y 
is positive, and has a very large positive value as 
Y approaches the integral values on either side. 
Where LY is even, the values of !Y are negative, 
and of extremely large magnitude as Y approaches 
the integral values on either side. 


OY Pi times Y 


Argument: Any numeric array, provided none 
of its elements has a magnitude greater than about 
2.303608646E75. 


Result: The value of the argument multiplied by 


pi, whose value is approximately 
3.141592653589793. 





?Y RollofY 


Argument: Any numeric array whose values are 
non-negative integers. 


Result: An array in which each element is an 
integer selected from among 1Y, so each is selected 
from the range DIO through Y-~QJO inclusive. 


Each element of the result is a pseudo-random 
number. That is, although the results are produced 
by an explicit and repeatable algorithm, they sat- 
isfy most tests of randomness. The value returned 
depends on the value of the system variable DRZ 
(“random link”) immediately prior to the execu- 
tion of ?Y. Each use of the function ?, as a side 
effect, resets the value of QRZ. If on different occa- 
sions you set the same value of [JRL and then use 
? on the same arguments in the same sequence, 
you will get the same results. 


The algorithm for generating random numbers 
utilizes two constants, a prime P+2147483647 
and a multiplier M«16807. (The prime is the lar- 
gest prime representable with 31 binary digits, the 
maximum size conveniently representable in the 


computer’s general registers. The multiplier is a 


primitive root of P that is close to the square root 
of P; the value 16807 is 7*5.) 


Each random element R that is generated causes 
at the same time a new value to be set for DRL, 
by the following formula: 


ORL+P | M@xDRL 
ReQIO+LYxOQRL+P 


in which L means the unfuzzed floor (as one 
would get when DCT is 0). This process is cyclic, 
and repeats after P-1 repetitions. 


For each of the argument’s elements that is 2*31 
or greater, the process goes through two cycles. Let 
the two-element intermediate step be called RL. 
The process may be represented as follows: 


RI«RL,P|MxRLI+«P|MxQRL 
Rex (RL+.x2*32 1)2128x16*14 
ORI+RECOLO+1 J 


Random numbers generated in this fashion are 
rectangularly distributed; you can get other dis- 
tributions by applying various transformations to 
the rectangular values generated by ?. The default 
value of [JRL in a clear workspace is 16807. 


LY Floor of Y 


Argument: Any numeric array. 


Result: An integer array in which the values of 
Y are rounded down. Each element of the result 
is the largest integer not greater than the corre- 
sponding element of the argument. 


When the system variable OCT, “comparison toler- 
ance,” has a value other than zero, the result of 
floor is said to be “fuzzed.” Informally, compari- 
son tolerance affects floor in the following way. A 
value that is exactly equal to an integer is unaf- 
fected: the result is that integer. A value that is 
close to an integer—that is, whose proportional 
departure from that integer does not exceed OCT 
—returns that integer as the result, even when the 
exact value is less than the integer. All other 
values give the next smaller integer. 


More formally, floor subject to [ICT can be defined 
by the following definition, in which the value of 
OCT in the environment becomes the explicit argu- 
ment CT (so that to find the floor of Y you should 
use [JCT FLOOR Y), and the primitive | is not 
subject to comparison tolerance. 


VY Z+CT FLOOR Y; OCT; NEAREST; 
ERROR; PERMISSIBLE 
[1] DCT<0 
[2] NEAREST+(xY)xLo.5+|Y 
[3] ERROR+NEAREST-Y 
[4] PERMISSIBLE+CTx1[ |Y 
[5] Z«NEAREST-ERROR>PERMISSIBLE 
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[Y Ceiling of Y 
Argument: Any numeric array. 


Result: An integer array in which the values of 
Y are rounded up. For an element of Y that is not 
an integer, the result is the next larger integer. 
That is, each element of the result is the smallest 
integer not less than the corresponding element of 
the argument. 


The ceiling function is influenced by the value of 
the system variable DCT (“comparison tolerance”). 


Informally, comparison tolerance affects ceiling in 
the following way. A value that is exactly equal 
to an integer is unaffected: the result is that in- 
teger. A value that is close to an integer—that is, 
whose proportional departure from that integer 
doesn’t exceed QCT— returns that integer as the 
result, even when the exact value is greater than 
the integer. All other values give the next larger 
integer. 


Formally, ceiling of Y is defined as -FLOOR -Y, 
where FLOOR is the defined function shown in the 
previous definition. 


~Y Logical negation of Y 


Argument: Any numeric array containing no 
values other than 0 or 1. 


Result: A numeric array (represented internally 


as Boolean) in which each element contains the 
value 1 where Y had 0, and 0 where Y had 1. 


ity 
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_ Chapter 16: 


- DYADIC SCALAR 
FUNCTIONS 





Shape of result and conformability of argu- 
ments 


A scalar dyadic function accepts arguments and 
returns a result according to the “ele- 
ment-by-element” rules, as follows: 


Same-shape arguments: If the arguments are of 
the same rank and shape, then the result is also 
of that shape. Each element of the result is found 
by evaluating the function for the corresponding 
element of the left argument and the corresponding 
element of the right argument. 


Scalar extension: If the arguments differ in 
rank but one is a scalar, the scalar is treated as 
if it had the rank and shape of the other argument, 
and the same value throughout. 


Single-element array: If the arguments differ in 
rank, and neither is a scalar, but one is an array 
containing only one element (but of any rank), the 
single-element argument is extended in the same 
way as a scalar. 


Both arguments are single-element arrays: If 
the arguments differ in rank, and neither is a 
scalar, but both are single-element arrays, the 
array of lower rank is extended in the same way 
as a scalar. 


Arithmetic sum and difference 


X+Y X plus Y 
X-Y X minus Y 


Arguments: Any conformable numeric arrays 
whose values are such that the magnitude of their 
sum (or difference) would not exceed the greatest 
representable magnitude (in the current im- 
plementation, about 7.237275). 


Result: A numeric array in which each element 


is the sum (or difference, as appropriate) of the 
corresponding elements of X and Y. 
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Arithmetic product and quotient 


XxY X times Y 
X:Y X divided by Y 


Arguments: Any pair of conformable numeric 
arrays whose values are such that the magnitude 
of their product (or quotient) would not exceed 
the greatest representable magnitude (in the cur- 
rent implementation, about 7.237E75). 


Result: A numeric array in which each element 
is the product (or quotient, as appropriate) of the 
corresponding elements of X and Y. 


In general, division by zero is undefined. When- 
ever the left argument contains an element whose 
value is not zero, but the corresponding element 
of the right argument is zero, the system rejects 
the expression as a DOMAIN ERROR. However, in 
APL systems, the special case 0+0 is permissible. 
There has been disagreement about what would 
be the most suitable result for 0+0. Some have 
suggested the most appropriate generalization 
would yield 0+0 «+ 1 while others have argued 
for 0+0 ++ 0. At present, in SHARP APL, 0+0 
gives you the result 1. 


X*Y X to the power Y 


Arguments: Any pair of conformable numeric 
arrays, subject to the following two restrictions. 
(1) The arguments may not be such that the re- 
sult would have a magnitude greater than the 
greatest representable magnitude (about 
7.237E75). (2) The result must be real. That is, 
you can’t get the system to extract an even root 
of a negative number. 


Result: A numeric array in which each element 
is an element of X raised to a power indicated by 
the corresponding element of Y. Raising a number 
to a fractional power is equivalent to extracting a 
root; for instance, the three-fifths root of X can be 
written X*3+5 or the square root of X as X*+2. 


In order to determine whether an even root of a 
negative left argument has been requested, in those 
cases where the left argument is negative and the 
right is fractional, the system attempts to decide 
whether the fractional right argument could be 
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represented by the ratio of two integers, and if so, 
whether the denominator of that approximation 
would be even or odd. 


When a rational approximation is possible, and 
would require an even denominator, then X*Y is 
undefined, and a DOMAIN ERROR is reported. 


When a rational approximation is possible but is 
found to consist of an odd denominator and an 
even numerator, the result is computed as 
(|X) *Y. 


When no rational approximation can be found, or 
when a rational approximation is possible but 
would require both the numerator and the denom- 
inator to be odd, the result is computed as 
~( |X) *Y. 


Xey Base X logarithm of Y 


Arguments: Any conformable numeric arrays all 
of whose elements are positive, and for which 
(@Y)+@X does not exceed the largest representable 
number (in the current implementation, about 
7.237E75). An element of the left argument may 
be 1 only if the corresponding element of the right 
argument is also 1. 


Result: A numeric array in which each element 
is the base-X logarithm of Y. That is, the power 
to which X would have to be raised to obtain Y. 
The dyadic logarithm X@Y is equivalent to the 
ratio of logarithms of the arguments considered 
separately; that is, X@®Y «> (®Y):8X. The 
APL interpreter makes use of that identity to eval- 
uate dyadic logarithm. 


The logarithm of 1 to any base is 0; however, 
since the system defines 0+0 to be 1, it defines 
1@1 as 1. 


X|Y The X residue of Y 


For positive arguments, this function is equivalent 
to the remainder function in arithmetic; that is, 
the amount you’d have left if you subtracted X 
from Y as many times as possible. It is also 
equivalent to Y modulo X. 


In APL, residue is also defined for negative left 
arguments (whereas in conventional arithmetic, 
the fraction is usually defined only for a positive 
modulus). 


A convenient way to picture the more general 
definition of residue is as follows. Imagine any 
number to be represented by its position on the 
number line. Then, starting at the value of the 
right argument Y, move along the number line in 
the direction of zero in a succession of hops of 
length |X. Continue this process until you reach 


X\Y 
/ \ 
modulus starting 


(size of point 
Jump) 


Notice that when X and Y are of opposite sign, the 
result of X |Y is the complement of the result you’d 
get if they had the same sign. That is, when neith- 
er X nor X|Y is zero, 


(-X)|Y <> X-X/Y 


Consider the results obtained when the modulus 
is 3 or 3 and the right argument is 8 or “8: 


stopping point 
when modulus 
is negative 


stopping point 
when modulus 
is positive 


ir 


Y 


starting point 


y stopping point 
starting point when modulus 


moving toward is negative 
zero 


zero, or, if that isn’t possible, until you reach the 
point that is nearest to zero but has the same sign 
as X. 


It follows from this definition that whenever Y is 
evenly divisible by X, then X|Y must be zero. But 
if X itself is zero, no number of hops of size 0 will 
approach any closer to zero, and so 
ol% < X. In all other cases, the result of 
X|Y is always closer to 0 than X is. 


stopping point 
when modulus 
is positive 


moving toward 
zero 





Arguments: Any pair of conformable numeric 
arrays. 


Result: A numeric array in which each element 
is the residue of an element of the right argument 
with respect to the corresponding element of the 
left argument. 
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The definition of residue depends on the defini- 
tions of floor and ceiling. Since floor and ceiling 
are subject to OCT (comparison tolerance), residue 
is likewise affected. That is made explicit in the 
following defined function RESIDUE, which gives 
the same result as the | primitive: 


Y ZX RESIDUE Y; IM; QUOT 


[1] QuoT<¥:X+X=0 

[2]  IM+(fQuor)=LQuOT 

[3] alS Y AN INTEGER MULTIPLE OF X? 

[4] af AND L SUBJECT TO DCT 

[5] Z+<(YxX=0) + (IMvwX=0)xY-XxLQUOT 
Vv 


In the result of X| Y, wherever an element of X is 
zero, the value of the result is identical to the 
corresponding element of Y. 


Wherever the quotient Y+X+X=0 is judged (subject 
to DCT) to be an integer, the corresponding ele- 
ment of the result is zero. That makes residue 
conform to the common-sense expectation that if 
X goes evenly into Y, there can’t be any remainder. 


When neither X=0 nor Y is an integer multiple of 
X, an element of the result is found by: 


Y-XxLQUOT 


X'Y Binomial coefficients; number of size-X 
subsets of Y items 


The dyadic function X!Y gives you the number of 
distinct ways you could select X items from a set 
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containing Y items; one common application is in 
determining coefficients of the terms of the bi- 
nomial expansion. The definition is generalized to 
include fractional and negative arguments. 


Arguments: Any pair of conformable numeric 
arrays. However, when an element of the right 
argument is a negative integer and the correspond- 
ing element of the left argument is not an integer, 
the function is undefined. A pair of arguments 
containing those values, or approaching them too 
closely, would require a result greater than the 
greatest representable magnitude, and is rejected 
as a DOMAIN ERROR. 


Result: When both X and Y are non-negative in- 
tegers, X!Y is equivalent to the function that in 
probability and statistics is called combinations, 
denoted by the capital C, but usually written so 
that the size of the population is on the left, and 
the size of the sample on the right, so that: 


yCx +> X!Y 


The successive coefficients of the binomial expan- 
sion of order N are obtained (assuming origin 1) 
from the expression (0,14)!N. For example, if 
you take the polynomial x+y to the tenth power, 
the resulting expression has eleven terms, corre- 
sponding to the various powers of x from the 
zeroth to the tenth, and you get their coefficients 
by the expression: 


(0,110) ! 10 
1 10 45 120 210 252 210 120 45 10 1 


For non-negative integers, the combinations func- The APL function X!Y is related to the complete 
tion can be computed from the factorial by use of Beta function by the following identity: 
the following identity: 
Beta (x,y) «> +Yx(X-1)!X+Y-1 
X!Y «<> (!Y):(!X)x!Y-X 

The tables on the following page illustrate the 
In APL, the factorial (that is, monadic !) is ex- results obtained from a range of positive and nega- 
tended to include both fractional arguments and tive integer arguments to the dyadic ! function. 
negative arguments; by exploiting that identity, the 
dyadic ! can also be extended to fractional and 
negative values. An element of the result is cal- 
culated by an algorithm selected from the table. 
The choice of algorithm depends on three tests. Is 
Y a negative integer? Is X a negative integer? Is 
the difference (Y-X) a negative integer? 


Algorithm for X!Y according to whether X or Y is a negative integer 
C 


Is a negative integer: Algorithm: 


0 0 (1Y)+(!X)x!Y-X 
1 0 
DOMAIN ERROR 
(1*X)xX!X-Y+1 
0 
case cannot arise 
("1*Y-X)x( | ¥+1)!(|X+1) 


0 
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XLY The minimum of X and Y 


Arguments: Any pair of conformable numeric ar- 
rays. 


Result: An array in which each element is taken 
either from the left argument or from the corre- 
sponding element of the right argument, whichever 
is smaller. Note that “smaller” means algebraical- 
ly smaller, so that ~2 is smaller than “1. Of 
course, where an element of X is exactly equal to 
the corresponding element of Y, it doesn’t matter 
which is taken. Minimum is not subject to com- 
parison tolerance. 


When dyadic L is modified by the reduction opera- 
tor /, the expression |/Y is the minimum along 
one axis of Y. Where that axis has length zero, its 
minimum is the identity element for the minimum 
function. In principle, that is plus infinity. In 
practice, the APL system returns its largest repre- 
sentable value, approximately 7.237£75. 


XTY The maximum of X and Y 


Arguments: Any pair of conformable numeric 
arrays. 


Result: An array in which each element is taken 
either from the left argument or from the corre- 
sponding element of the right argument, whichever 
is larger. Note that “larger” means algebraically 
larger, so that 1 is larger than 2. Of course, 
where an element of X is exactly equal to the 
corresponding element of Y, it doesn’t matter 
which is taken. Maximum is not subject to DCT, 
comparison tolerance. 


When dyadic [ is modified by the reduction opera- 
tor /, the expression [/Y is the maximum along 
one axis of Y. Where that axis has length zero, its 
maximum is the identity element for the maximum 
function. In principle, that is minus infinity. In 
practice, the APL system returns the smallest re- 
presentable value, approximately 7.237275. 


Logical functions 


XAY X and Y 
XVY X or Y 
X*Y X nand Y 
XxY X nor Y 


Arguments: Any pair of conformable numeric ar- 
rays containing no values other than 0 or 1. 


Result: A numeric array (represented internally 
as Boolean) in which each element is either 0 or 
1. The result produced by each of the four func- 
tions can be summarized as follows: 


XAY An element of the result is 1 where both X 
and Y are 1, and 0 otherwise. 


XVY An element of the result is 1 where either 
X or Y (or both) is 1, and 0 otherwise. 


XAY An element of the result is 1 where either 
X or Y (or both) has 0, and 0 otherwise. 


XY An element of the result is 1 where both X 
and Y are 0, and O otherwise. 


Alternatively, the four functions are summarized 
in the tables: 





Watch out: In popular English speech, the phrase 
“X or Y” is understood to mean “one or the other 
but not both.” In logic, that is called an “exclusive 
or.” You get that result in APL by using the 
function z “not equal.” 
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Propositions on equality and inequality 


X=Y X is equal to Y 
XzY X is unequal to Y 


Arguments: Any pair of conformable arrays. 


Result: A numeric array in which an element is 
1 where the proposition is true for the correspond- 
ing elements of X and Y, and 0 otherwise. 


Whenever a number is compared with a character, 
they are reported to be unequal. That statement 
includes characters that are numerals: the charac- 
ter '2' isn’t equal to the number 2. 


In principle, judgments of equality are subject to 
OCT, comparison tolerance. In practice, this mat- 
ters only when either argument (or both) is repre- 
sented internally as floating point. Two numbers 
are judged to be equal if they are equal within a 
factor of OCT. The effect of DCT is thus relative. 
The range within which two numbers are judged 
to be equal is [CT times the magnitude of which- 
ever has the greater magnitude. The effect of 
OCT on the behaviour of = can be modelled by the 
defined function TEQ (for “tolerant equals”). In 
the definition, the symbol < indicates a strict less- 
than-or-equals, not subject to OCT. 


Subject Not subject 
to DCT to (ICT 


X TEQ) Y + (|X-¥) < OCTx(|X)T1Y 


The effect of [CT on = is 


X#Y <> ~X TEQ Y 


In SHARP APL, there’s a limit to the size you 
can give OCT. It must be less than 16* 8 which 
is about 2.328306437E 10. A consequence of 
this rule is that no integer in the range of plus or 
minus 2*31 can be judged equal to another. For 
any comparison to take place (even comparison of 
a number with a character), DCT must have a 
valid value. 
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Propositions on numerical inequality 


X<Y X is less than Y 

X<Y X is less than or equal to Y 
X2Y X is greater than or equal to Y 
X>Y X is greater than Y 


Arguments: Any pair of conformable numeric 
arrays. (APL has no defined collating sequence 
for characters, and does not include characters in 
the domain of any of these functions.) 


Result: A numeric array (represented internally 
as Boolean) in which an element is 1 where the 
proposition is true for the corresponding elements 
of X and Y. 


Each of these functions is influenced by the value 
of the system variable DCT, comparison tolerance. 
Here is the way OCT affects them. You can define 
tolerant inequality in terms of strict inequalities 
(that is, inequalities independent of OCT) and 
tolerant equality. Let “tolerant equality” be repre- 
sented by the function TEQ, as shown in the sec- 
tion, “Propositions on Equality and Inequality.” 
Then the numeric inequality functions are related 
to tolerant equality as follows: 


Subject With only TEQ 
to DCT subject to DCT 


(X<Y) A ~X TEQ Y 
(X<Y) v X TER Y 
(X2Y) v X TEQ Y 


(X>Y) aA ~X TEQ Y 


XoY Family of circular functions X applied to 
Y 


The circular functions constitute a family of relat- 
ed functions. Taken individually, each of them is 
monadic. However, in APL, the set of them is 
treated as a single dyadic function. The left argu- 
ment indicates which monadic function you mean. 


The right argument is the data to which the func- 
tion you’ve selected is applied. There are fifteen 
possible values of the left argument, corresponding 
to fifteen members of the family of circular func- 
tions. They are shown in the table. 


Function selected by left argument of o 
a 


Magnitude Non-negative Negative 
1 -x? 
arcsin x 
arccos x 
arctan x 
x? -] 
arsinh x 


arcosh x 


artanh x 





Because O is a dyadic scalar function, values in the 
left argument can be paired with values in the 
right argument according to the usual rules for 
scalar functions: that is, element-by-element, outer 
product, or inner product. For example, if Y is a 
three-element vector, and you want the sine of the 
first element, the cosine of the second, and the 
tangent of the third, you get that by using a left 
argument containing the numbers 1 2 3, which in- 
dicate, respectively, the sine, cosine, and tangent: 


123 0Y 


Moreover, being a scalar dyadic function, the cir- 
cle can be used in an outer product. For example, 
if you need to apply each of the fifteen possible 
functions to every one of the elements of Y, you 
can obtain that 15-by-3 matrix by the expression: 


(C 8+115)0.0Y 


Similarly, O can be used in inner products. For 
example, if S is a scalar, you can get the sum of 


the hyperbolic sine and cosine of S by 5 6+.0S, 
which, as it happens, is equal to the exponential 
xS, while 5 6+.0S is equivalent to the natural 
log @S. 


Again, being a scalar dyadic function, © can be 
used in reductions and scans—although it isn’t 
easy to think of situations in which that is readily 
useful. To find the value of the argument equal 
to its own cosine (that is, Y=20Y), you could write 
0/99p2. 


Arguments of 0: A pair of conformable numeric 
arrays. Each element of the left argument must be 
an integer from the set 7 to 7. 


An element of the right argument can have any 
value, subject to two sorts of exceptions. 


First, as with any dyadic function, a combination 
of values in the left and right argument that would 
result in a number having a magnitude larger than 
the system’s largest representable magnitude is 
rejected as a DOMAIN ERROR. 


Second, there may be further restrictions on the 
right argument, depending on what function is 
selected by the left argument; these are discussed 
in the paragraphs that follow, devoted to the var- 
ious members of this family of functions. 


Classifications of the members of the 0 family: 
A function indicated by a left argument whose 
magnitude is 0 or 4 is one of the Pythagorean 
functions. They are illustrated by constructions on 
a unit circle, shown in the figure, “The Pythagore- 
an and Circular Functions.” A function indicated 
by a left argument whose magnitude is 1, 2, or 
3 is one of the circular functions, sine, cosine, and 
tangent, or its inverse. A function indicated by a 
left argument having magnitude 5, 6, or 7 is one 
of the hyperbolic functions or its inverse. 


Generally speaking, the left arguments of © have 
been chosen so that reversing its sign gives you the 
corresponding inverse function. In conventional 
notation, the arcsine is sometimes written sin 1, 
as a way of indicating that it is the inverse of sin. 
In APL, for any of the circular or hyperbolic func- 
tions, the inverse of a function AOX is obtained by 
(-A)OX. 
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A function whose right argument is an arc (sin, 
cos, tan; that is, 10X, 20X, and 30X) takes an 
argument expressed in radian measure. Similarly, 
a function whose result is an arc (arcsin, arccos, 
arctan; that is, 10X, 20X, and 30X) returns a 
result expressed in radian measure. You can think 
of a quantity expressed in radians as an angle, or 
as the length of an arc along the unit circle, or as 
twice the area of a sector of the unit circle. The 
corresponding unit for a hyperbolic function is 
twice the area of a sector of the unit hyperbola. 


o4 HOY The Pythagorean functions of 


The result of the function 0OY can be represented 
geometrically as the altitude of a point on the unit 
circle above a point Y on the horizontal axis. In 
the figure, “The Pythagorean and Circular Func- 
tions,” the altitude PR +> 0OOR (and similarly 
OR «> OOPR). Since an altitude for the unit circle 
is defined only for points not more than 1 removed 
from the origin, the domain of 00 is from 1 to 
T: 


In the figure, “The Pythagorean and Circular 
Functions,” the line PT is tangent to the unit circle 
at P, and hence perpendicular to the radius OP, so 
that OPT is a right triangle one of whose legs has 
unit length. The function 40 gives the length of 
the hypotenuse OT as a function of the length of 
the other leg, so that OT «+ 4oPT. The function 
T40 gives the length of that leg as a function of 
the length of the hypotenuse OT, so that 
PT <> yoOT. Consistent with this geometrical 
interpretation, the argument of 40 may have any 
numeric value, but the argument of "40 is restrict- 
ed to numbers whose magnitude is 1 or greater 
(since the hypotenuse of a triangle with unit leg 
can never be less than 1). 


The circular 
functions of Y 


For an argument Y in radians, 10Y is the sine of 
Y, and 20Y is the cosine of Y. The tangent is the 
ratio between them: 


3OY +> (10Y)+20Y +> +71 20.0Y 
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These three functions are periodic; the value of the 
result for sine and cosine repeats every 2 pi 
radians of the argument. Thus, if A is 1 or 2, then 
AoY «+ A0(02)|Y. The result of the tangent 
repeats every pi radians of the argument, so that 
30Y <> 30(01)|Y. 


The sine and cosine are linked by the following 
identities involving the Pythagorean function: 


10Y <> 0020Y and 20Y +> 0010Y 


The reciprocal functions secant, cosecant, and co- 
tangent may be obtained by +10Y, +20Y, and 
+30Y; the cotangent can also be stated 
+42 10.0Y, which avoids the DOMAIN ERROR 
when 30Y is zero. In the figure, OT is the secant, 
OS is the cosecant, and PS is the cotangent. 


THE PYTHAGOREAN AND CIRCULAR 
FUNCTIONS 


sine 
cosine 
tangent 
cotangent 
secant 
cosecant 


© 


(Reprinted with permission from K.E. Iverson, 
Elementary Analysis, APL Press.) 





THE HYPERBOLIC FUNCTIONS 


sine 
cosine 
tangent 
cosecant 
secant 
cotangent 


© 


TQ=50B hyperbolic sine 
OT=60B hyperbolic cosine 
VW=70B hyperbolic tangent 
PS=+50B hyperbolic cosecant 
OR=+60B hyperbolic secant 
UV=+70B hyperbolic cotangent 
B+ 5030A gudermannian 


(Reprinted with permission from K.E. Iverson, 
Elementary Analysis, APL Press.) 


The figure, “The Hyperbolic Functions,” extends 
the geometric constructions shown in the figure, 
“The Pythagorean and Circular Functions.” Once 
again, O is the centre of a unit circle (so that OP 





is 1). The two arms of the unit hyperbola are 
shown tangent to it, with the major axis of the 
hyperbola along the horizontal axis of the figure. 
As before, the line SPT is tangent to the unit circle. 
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For the angle A (measured along the arc IP), the 
altitude PR represents the sine of A, and OR the 
cosine of A, while PT is the tangent of A. 


104 <> RP 
20A +> OR 
304 <> PT 


The inverse functions 1 20Y have domains re- 
stricted to values not greater in magnitude than 
1. Since sine and cosine are cyclic functions, a 
given sine or cosine is, in principle, related to any 
of an infinite number of arcs, differing from each 
other by successive multiples of 2-pi. For a given 
sine, 10 returns the arc lying at or between -pi/2 
to pi/2 radians. For a given cosine, ~ 20 returns 
the arc lying at or between 0 and pi radians. Simi- 
larly, for a given tangent, 30 returns the arc 
lying between -pi/2 and pi/2 radians. 


The hyperbolic 
functions of Y 


The hyperbolic cosine relates the coordinates of a 
point on the unit hyperbola to twice the area of 
the hyperbolic sector bounded by the following 
three curves: a line from the origin to that point, 
the unit hyperbola itself, and the major axis of the 
hyperbola. In the figure, “The Hyperbolic Func- 
tions,” @ is such a point on the unit hyperbola, 
with coordinates U and T; the area is shown shad- 
ed. If (as it is in the figure) the unit hyperbola 
is oriented so its major axis lies horizontally, the 
hyperbolic sine is the Y-coordinate of that point 
Q, and the hyperbolic cosine is the X-coordinate 
of that point Q. The hyperbolic tangent (by analo- 
gy with the circular tangent) is the ratio of the 
hyperbolic sine to cosine. 


The inverse hyperbolic functions are arsinh, ar- 
cosh, and artanh; the “ar” prefix indicates 
“area,” whereas the prefix “arc” used with the 
inverse circular functions indicates “arc.” The in- 
verse hyperbolic functions give you twice the area 
of the hyperbolic sector described by its sinh, cosh, 
and tanh, respectively. If X is a value of the hyper- 
bolic sine and Y is a value of the hyperbolic cosine, 
and Z is their ratio, then the area enclosed is equal 
to 50X «+ “60Y +> ~702. 
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The result returned for the area of the hyperbolic 
sine and cosine has the same sign as its argument. 
Since, in principle, sinh and cosh can take on any 
values, both the domain and the range of arsinh 
and arcosh are infinite. Since sinh must always be 
less than the corresponding value of cosh, tanh has 
a magnitude that approaches but can never reach 
1. In practice, the areas of the hyperbolic functions 
are evaluated by exploiting the following identities: 


Tsoy <> @X+u4u0X 
Teo% «> @X+ 4OX 
TJO% <> 0.5x@(1+X)#(1-X) 


This method of computation gives 50 and ` 60 
an effective domain of all numbers whose magni- 
tude is roughly less than 1£37; the results have 
magnitude roughly less than 85. The artanh func- 
tion ~70 has an effective domain of numbers 


whose magnitude is roughly less than 18. 


Chapter 17: 


NON-SCALAR 
PRIMITIVE 
FUNCTIONS. 
(OTHER THAN 
SYSTEM 
FUNCTIONS) 





In this chapter, definitions are presented for each 
of the primitive functions that is denoted by a 
single symbol but is not a scalar function. The 
functions are described in the same order in which 
they were listed in the chapter, “Classification of 
APL Primitive Functions and Operators.” Where 
the same symbol has both a monadic meaning and 
a dyadic one, the monadic meaning is described 
first. 


pY Rho Y; shape of Y 
Argument: Any array. 


Result: A numeric vector of integers. The vector 
contains one element for each axis of Y. Thus, the 
number of elements in the result of pY is the num- 
ber of axes that Y has; that is, the rank of Y. The 
value of each element is the length of the corre- 
sponding axis of Y. 


Notice that when Y is a scalar (that is, has no 
axes) the result of pY is a vector containing no 
elements (that is, an empty vector). 


Since the length of the vector produced by pY is 
equal to the rank of Y, then in general, the rank 
of Y is found by ppY. For example: 


Y<6 
pY 
(empty vector) 
ppY 
0 
Y<i5 
pY 
5 
ppY 
1 
Y<+2 3p16 
pY 
2 3 
opY 
2 


| 
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XoY X rho Y; the X reshape of Y 


Right argument: Any array. However, the right 
argument may be empty only if the left argument 
contains a zero. An array is empty if one or more 
of its axes has length zero. Thus, the right argu- 
ment may be empty only if the result to be 
produced is also empty. If you attempt to use re- 
shape to create an array that isn’t empty from an 
empty right argument, the system rejects the 
expression with the message DOMAIN ERROR. 


Left argument: A vector of integers, indicating 
the length of each of the axes of the array to be 
formed. The system accepts a scalar as equivalent 
to a 1-element vector. 


Result: An array whose shape comes from X but 
whose values comes from Y. The positions in the 
result are filled in row-major order, by taking the 
elements of Y in row-major order. (See “Note on 
Row-major Order.”’) 


If the total number of elements required for the 
result (that is, x/X) is fewer than the number of 
elements in Y, elements are taken from Y in row- 
major order until the result is complete, and the 
remaining elements of Y are ignored. 


If the result requires more elements than Y con- 
tains, the elements of Y (always in row-major 
order) are repeated cyclically in the result. For 
example, suppose Y is a two-by-five matrix con- 
taining the following values: 


1 2 3 4 5 
6 7 8 9 10 


Then a result containing fewer elements than Y 
might be obtained as follows: 


ToY 


or by: 
2 4pY 
1 2 3 4 
Sy Lbs. T, 8 


And a result requiring more elements than there 
are in Y by expressions such as the following: 


or 


œ 
WO 
|e 
(o>) 
PR 
N 
w 
F 


Note that if X is a vector longer than pY but con- 
taining pY as its last elements, the effect is to 
replicate Y completely at each of the positions 
along the new axes. For example: 


pY 


If the shape of the result differs from the shape 
of the right argument, a systematic pattern may 
be generated. For example: 

4p5+t1 


4 
0 
0 
0 
1 


oo OF 
ooroo 
OrROO 


The shape of a scalar is empty, so to produce a 
scalar, you use an empty left argument for p. Since 
the type of an empty vector doesn’t matter, you 
could get a scalar from Y equally well by: 


(10)pY or by ''pyY 
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The result produced by reshape has a shape equal 
to the value of X. The only exception is that the 


system tolerates a scalar X for a 1-element vector. 
Thus: 


oXpY +> ,X and (pY)pY + Y 


Note on row-major order 


Row-major order is a term borrowed from matrix 
algebra. Referring to a matrix, it means that you 
take first the element located in the first row at 
the first column, then the one in the first row, 
second column, and so on, stepping through all the 
columns before moving to the next row. That can 
be applied to arrays of any rank: you count off 
through the positions along the last axis, then 
along the next to last, and so on. This is the same 
order as produced by the function ravel, (defined 
elsewhere in this chapter), so that: 


XoY <> Xp,Y 








oY Reverse of Y 

eY  First-axis reverse of Y 
Argument: Any array. 

Result: An array having the same rank and 


shape as Y, but with the sequence of elements 
along one of its axes reversed. For example: 


Y 
COPENHAGEN 
LUXEMBOURG 


oY 
NEGAHNEPOC 
GRUOBMEXUL 





mn 














Dc |BlAl 


result 


The expression $Y reverses along Y’s last axis, 
while ƏY reverses along Y’s first axis. 


ƏY 
LUXEMBOURG 
COPENHAGEN 


If the axis along which reversal takes place has 
length 1 or 0, the result is the same as the argu- 
ment. 


Operator: The reversal function may be modi- 
fied by the axis operator. That lets you state ex- 
plicitly along which axis you want reversal to take 
place. You write the axis operator as an expression 
enclosed in brackets immediately to the right of the 
function symbol $ or ©. The value inside the 
bracket must be a single-element array whose 
value (taking into account the index origin DZO) 
indicates one of the axes of Y. 


Suppose the expression that indicates an axis is 
I. Then 


${I] Y and of[I] Y 


mean the same thing; that is, reversal along the 
Ith axis of Y. 
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[A[B|c[D| 

o(1)y 
HEH DCH+H 
[A[Bic|D| 


result 


oo(ijy 


[A]B|c|D 
EI FIG|A 


Y 


ear 
[HIG |F IE | 
[D|c |B iA | 


result 





XoY The X rotate of Y 
Ney The X first-axis rotate of Y 


Right argument: Any array. 


Left argument: An array of integers indicating 
by how much the elements of Y are to be rotated 
along one axis. 


In general, the left argument X must have rank 
one less than the rank of Y. The axes of X corre- 
spond to all the axes of Y except the axis along 
which rotation takes place. Hence, the axes of X 
must have the same length as the axes of Y (except 
for the axis of rotation, which isn’t represented at 
all in X). 


If you’re rotating Y everywhere by the same 
amount, then the left argument X may be a scalar. 
The system also accepts a single-element array of 
any rank as if it were a scalar. 


Result: An array of the same rank and shape as 
Y, but with the elements cyclically rotated along 
one axis. 


The function XY means rotation along the last 
axis, while XCY means rotation along the first axis. 


Operator: The rotate function may be modified 
by the axis operator. That lets you state explicitly 
along which axis you want rotation to take place. 
You write the axis operator as an expression en- 
closed in brackets immediately to the right of the 
function symbol > or e. The value inside the 
bracket must be a single-element array whose 
value (taking into account the index origin DIO) 
indicates one of the existing axes of Y. 


212 1ġ[1]Y 


- 
Z 

fej 

z 

a 

c 

= 

S 

> 

z 

5 


result 





Direction of rotation: The value in each ele- 
ment of X indicates the amount by which the cor- 
responding vector within Y is to be rotated. The 
sign of that number indicates the direction of rota- 
tion. Positive rotation moves elements toward the 
front (and those already at the front take the va- 
cated positions at the end). Thus: 


36'ABCDEFGHIJK' 
DEFGHIJKABC 


143 NON-SCALAR PRIMITIVE FUNCTIONS (OTHER THAN SYSTEM FUNCTIONS) 


eal 


Negative rotation moves elements towards the end 
(and those already at the end take the vacated 
positions at the front). Thus: 


'~36' ABCDEFGHISK' 
IJKABCDEFGH 


Because rotation is cyclical, rotating a 10-element 
vector by 10 positions (or by 20 or by a 100, etc.) 
brings it back to its original position. Thus, the 
amount of rotation is effectively modulo the length 
of the axis along which rotation takes place. A 
negative rotation is equivalent to a positive rota- 
tion by the complementary amount. For example, 
suppose Y is the eleven-element vector: 


Y<' ABCDEFGHIJK' 


11| 3 
8 

BOY 
IJKABCDEFGH 


Example of rotation of rank-3 array: Suppose 
Y is the following 2-by-3-by-10 array of charac- 
ters: 


COPENHAGEN 
LIBREVILLE 
LUXEMBOURG 


WELLINGTON 
MONTEVIDEO 
WASHINGTON 


To rotate that rank-3 array, you need a rank-2 
left argument. If rotation is to alter the positions 
of the elements with respect to columns, then you 
need a 2-by-3 left argument. Suppose X is the 
following 2-by-3 matrix: 


3 6 19 
“3 6 19 


In the example, the third column of X shows rota- 
tion by an amount greater than the length of the 
axis. Since the axis has length 10, rotation by 19 
has the same effect as rotation by 10|19, and 
rotation by 19 has the same effect as rotation by 
10/19. 





That expression gives you positive rotation for the 
three rows in the first plane, and negative rotation 
for the three rows in the second plane: 


XOY 
ENHAGENCOP 
ILLELIBREV 
GLUXEMBOUR 


TONWELLING 


EV IDEOMONT 
ASHINGTONW 


&Y  Transpose of Y 


Argument: 


Any array. 


petit 








result 


Result: An array of the same rank, but with its 
axes arranged in an order that’s the reverse of 
their order in Y. If the argument Y has rank 1 or 
0, the result is the same as the argument. If the 
argument Y is a matrix (rank 2), the result has 
rows where Y has columns, and columns where Y 
has rows. For example, suppose Y is the following 
3-by-10 matrix of characters: 


COPENHAGEN 
LIBREVILLE 
LUXEMBOURG 
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Then XY gives you a 10-by-3 matrix in which the 
names of the cities now appear down the columns: 


XY 
CLL 
OIU 
PBX 
ERE 
NEM 
HVB 
AIO 
GLU 
ELR 
NEG 


The transpose of a rank-3 array moves the last 
axis (columns) of the argument so that it becomes 
the first axis (planes) of the result. For example, 
if Y is the 2-by-3-by-6 array 


LONDON 

ATHENS 

OTTAWA 

PEKING 

MOSCOW 

PRAGUE 

then XY is a 6-by-3-by-2 array: 
LP 


OP 


The shape of the result is the reverse of the shape 
of the argument: 


pY <> pY 


XXY The X transpose of Y 

Right argument: Any array. 

Left argument: A vector of integers. 

The left argument X indicates what is to be done 
with each of the axes of Y. It must contain one 
element for each axis of Y; its length must be equal 


to the rank of Y. 


(When Y has rank 1, the system also accepts a 
scalar X where, strictly speaking, you’d expect a 


-1-element vector. But transposition has nothing to 


do unless Y has at least two axes.) 


The positions within the left argument X corre- 
spond to the various axes of Y. The values within 
the left argument X refer to the axes of the result. 
The result can have any rank that’s greater than 
0, but not greater than the rank of Y. 


The elements of X must be a dense set of integers. 
That is, when the desired result has rank N, X 
must include each member of 1N at least once. For 
example, if you want a rank-3 result (and DIO is 
1), this is a possible value for X: 1 3 2 3, where- 
as the following is not: 1 4 3 4. 


Result: An array formed by permuting or map- 
ping together the axes of Y. The result contains 
one axis for each distinct number in X. If X doesn’t 
contain any repetitions, then the rank of the result 
is the same as the rank of the right argument Y. 
Suppose Z«X¥Y, then 


pZ +> (pY)(X] 
pY <> (pZ)[X] 


Consider first the result you get when all the num- 
bers in X are distinct. All the axes of Y are includ- 
ed in the result (indeed, all the elements of Y). 
Only the order of the axes is changed. Suppose 
Y has 4 axes, and that OIO is 1. Then the expres- 
sion 


3 1428Y 
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314 2ayY 


axes of Y 


X transpose 


axes of result 


shape of Y 


shape of result 


index(es) of Y 


index(es) of result 


[AlB] 
CiD 
EIF| 

lol 


[>x wy 
q, 


[5 


lofo]z 
v= 


«| 
‘| 


=]S 
|S 


ke 


SR 
D |5 











xnl fe] 
[s[m | a] 


BOAT CPS” Pea 
1 ojei te reir i 
beso C-dalisous 














says that the first axis of Y becomes axis 3 of the 
result; the second axis of Y becomes axis 1 of the 
result; the third axis of Y becomes axis 4 of the 
result; and the fourth axis of Y becomes axis 2 of 
the result. 


If the left argument of & is consecutive integers, 
then the axes are returned in the same positions 
they had before, and so (ippY)&Y <— Y. If the 
left argument contains consecutive integers in re- 
verse order, then the sequence of the axes of Y is 
reversed, which is the result you get from the mo- 
nadic transpose: (dippY)&Y <> XY. The number 
of different ways you can transpose Y but still 
retain all of its axes is the number of permutations 
of that number of axes; that is, !ppoY. 


permutation of axes of Y 


———, 
cS 


1st block, 
Ist plane 
of result 





When X contains repetitions, the number of dis- 
tinct numbers in X is less than the rank of Y, and 
so the rank of the result is also less than the rank 
of Y. Thus, the rank of the result may not be 
greater than the rank of Y, but it may be less. 
Then 


8 (pZ) +> (pY)L.+([/p¥)xXe.#1([/X)+-00 


Consider what happens when the left argument 
X contains repetitions. Suppose (when DIO is 1) 
that you have the following 4-element left argu- 
ment: 1 3 2 3. The value 3 occurs both in the 
second and the fourth positions. That means that 
axis 3 is to be formed from both the second and 
fourth axes of Y. Two distinct axes of Y are 
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mapped into a single axis of the result. That is 
done by taking from Y only those elements whose 
1 3 2 38Y position is the same on those axes. Thus, 
1 3 2 3&Y means that axis 3 of the result is to 
contain each element whose position on the second 
X transpose a is equal to its position on the fourth axis of 


axes of Y 


axes of result 


shape of Y 


shape of result 


Other Mappings 


index(es) of Y 











12 2&2 


index(es) of result 


axes of Z 


X transpose 


axes of result 


shape of Z 





shape of result 
result 


mapping of axes of Y index(es) of Z ry 


Less erry bed 


Ld 


+ H ot 
index(es) of result Ia 


Ist plane 
of result : 
mapping of axes of Z 





2nd plane 
of result 
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By mapping axes together, you are selecting a di- 
agonal. For a 4-axis array Y, the expression 


111 1Y 
would give you a vector formed by: 
Y[1;1;1;1], Y[2;2;2;2], Y[3;3;3;3] 


and so on. 


1 1 2&2 


[ABCD] mapping of axes of Z 
aRt Se 


result 


mapping of axes of Z 





Similarly, for a matrix Y, 1 18Y is a vector from 
the main diagonal. 


If the axes that are mapped together differ in 
length, the number of positions common to both 
axes is only as great as the length of the shortest 
axis. For example, if Y is a 3-by-10 matrix of 
characters, then 1 18Y picks out only the elements 
shown as O and ignores those shown as o: 


Oooo0oo0o00000 
oOoooo0o0000 


ooOo0o0o00000 


>Y The ravel of Y 
Argument: Any array. 


Result: A vector containing all the elements of 
Y. When Y is a scalar, ,Y gives you a 1-element 
vector. 


The elements of Y are taken in row-major order. 
(See also “Note on Row-major Order.” ) Elements 
are selected by cycling through all the indexes of 
the last axis of Y, then of the next-to-last, and so 
on, so that the first axis of Y is selected last. For 
example, if Y is a 3-axis array whose shape is 
2 3 4, then the 24 elements of ,Y are selected by 
taking them from Y in the following sequence: 


Yt 1; 1] 
YEI; Ag 2] 
Yeti 3] 
Y[1; 1; 4] 
Y(1; 2; 1] 
Y[1; 2; 2J 
Y[1; 2; 3] 
Yli: 2; 4] 
YET 3544] 
Y[1; 3; 2] 
Y[1; 3; 3J 
Y[1; 3; 4] 
YEZ Add, 
de 1372] 
Y[2; 1; 3] 
Y[2; 1; 4] 
Y[2; 2; 1] 
VEZ 25. 24 
Y[2; 2; 3] 
PEs 2; 4] 
Y[2; 3; 1] 
Y[2; 3; 2] 
Y[2; 3; 3] 
VE2s- 3: 1b] 


X,Y X catenated to Y 
X laminated to Y 


The dyadic function , forms a new array by join- 
ing the two arrays that are its arguments. Joining 
takes place along a single axis. 
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If X is a vector containing characters as follows: 
X+' ABCDEF' 

and Y is a vector containing characters thus: 
Y«'SPQR' 


then you join them to form a single array by the 
expression: 


X,Y 
ABCDEFSPQR 


When the axis along which X and Y are joined is 
one of their existing axes, the function is called 
catenation. When they are joined along a new 
axis, the function is called lamination. Because 
the rules that govern conformability of the argu- 
ments depend on the way you use the axis opera- 
tor, use of the axis operator with , will be dis- 
cussed before rules governing the arguments and 
result are summarized. 


Use of the axis operator with catenation and 
lamination: Unless you specify otherwise (by 
using the axis operator) the axis along which join- 
ing takes place is the last axis. Because catenation 
doesn’t add any new axes, but simply extends the 
length of one of the existing axes, the result has 
the same rank as the arguments. (If you join two 
scalars, since scalars haven’t got any axes, the axis 
operator doesn’t apply; in that case, joining must 
be along a new axis, and you get a 2-element 
vector. ) 


The axis operator may be used to specify explicitly 
which axis you mean. If you use the axis operator, 
you write it as an expression enclosed in brackets, 
immediately to the right of the comma symbol. For 
example, to join X and Y along axis J, you’d write 


X,CI] Y 


The expression enclosed in brackets must have a 
value that indicates which one axis you mean. If 
the value of I is an integer, and indicates one of 
the existing axes of X or of Y (taking into account 
the index origin DIO), then the function is catena- 
tion, and joining takes place along axis J. 


But if J is not an integer, then the axis operator 
provides that the arguments must be joined along 
a new axis. In that case, the function is lamina- 
tion. The result of lamination has one more axis 
than either argument. 


Axis-numbers to indicate lamination: You 
can’t use just any fraction to indicate lamination. 
It must be a fraction that differs from the number 
of an existing axis by an amount less than 1. The 
purpose of the fraction is to indicate where the 
new axis is to be placed with respect to the exist- 
ing axes. It could be ahead of the first axis, or 
after the last one, or between any of the existing 
ones. The position that I has with respect to the 
existing axis-numbers tells you where the new axis 
will be with respect to the existing axes. For ex- 
ample, if the existing axes have the numbers 
1 2 3, and the value for the axis operator is 
2.3, then the new axis is to be inserted after axis 
2 and before axis 3. 


To indicate a new axis for lamination, the argu- 
ment of the axis operator may be any fraction that 
differs from an existing axis-number by an 
amount less than 1. Thus, if the axis numbers for 
X and Y are 0 1 2, then any of the following 
would be permissible values of I to indicate lami- 
nation along a new axis: 0.5 1.9 1.5 2.01, 
but none of the following would be: 
oh, bok ses 


Arguments of catenation or lamination: Any 
pair of simple arrays, subject, at present, to the 
restriction that they must both be of the same type 
(that is, character or numeric). However, if one 
of them is empty, it doesn’t matter what type the 
other is. 


The arguments must conform in shape. Corre- 
sponding axes of the two arguments must have the 
same length. They must match in length along all 
axes except the axis along which joining takes 
place. For lamination, the two arguments must 
have the same rank. For catenation, they must 
either have the same rank, or differ in rank by 1. 


If one of the arguments is a scalar but the other 
is not, the scalar is replicated to match the other 
argument in all axes in which joining does not 
take place. 
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Rules applying only to catenation: When X 
and Y have the same rank, the axis along which 
catenation takes place may have any length. For 
all the other axes, the length of an axis in X must 
match the length of the corresponding axis in Y. 


When the arguments X and Y differ in rank by 
one, the axes of the lower-rank argument must 
match in length all of the axes other than the one 
along which catenation takes place. 


Result: An array containing all the elements of 
both X and Y. 


When the function is catenation, the result has the 
same rank as the arguments. If the arguments dif- 
fer in rank, the result has the same rank as the 
argument whose rank is greater. 


When the function is lamination, the result has 
rank one more than the rank of the arguments. 


Each axis of the result has the same length as the 
corresponding axis of the arguments, except that 
the length of the axis along which catenation took 
place has the sum of the lengths of that axis in 
the two arguments. When the function is lamina- 
tion, the new axis has length 2. 


Example showing catenation of arrays of the 
same rank: Suppose X and Y are both matrices. 
X is a 3-by-6 array of characters, and Y is 3-by-4, 
as follows: 


X Y 
ITALY ROME 
NORWAY OSLO 
PERU LIMA 


It’s all right to join these arrays along their last 
axis because the lengths of their other axes corre- 
spond. The result is an array with shape 3 10: 


X,Y 
ITALY ROME 
NORWAYOSLO 
PERU LIMA 


You can catenate two matrices along their first 
axis if they have the same number of columns. For 
example, suppose YY is a matrix that resembles 
Y but has 6 columns but only 2 rows (so that 
LIMA is not included). Then, you could join them 
vertically: 


X,{O70] YY 
ITALY 
NORWAY 
PERU 
ROME 
OSLO 


Example showing catenation of arrays that dif- 
fer in rank: If the arrays differ in rank, it must 
be by 1 (except for the special case that one array 
is a scalar). The axes of the lower-rank array 
must match in length all of the axes of the other 
array, except the one along which catenation is to 
take place. So if X is a 3-by-6 matrix, you extend 
its first axis (rows) by catenating a vector of 6 
elements, or you can extend its last axis (columns) 
by catenating a vector of 3 elements: 


'NATION',{OIO] X 
NATION 
ITALY 
NORWAY 
PERU 





'123',(O70+1] X 
1ITALY 
2NORWAY 
3PERU 


Catenating a scalar: When you catenate a sca- 
lar to a non-scalar array, it is replicated to match 
in length all the axes, except the one along which 
catenation takes place. So if you catenate a scalar 
S+'x' along the last axis of X, you’ll get the same 
effect as catenating a 3-element vector (because X 
has 3 rows): 


X, C[OI0+1] S$ 
ITALY * 
NORWAY* 
PERU x 
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And if you catenate the scalar S along the first 
axis, you'll get a new row with 6 elements, since 
X has 6 columns: 


X,(OI0} S 
ITALY 
NORWAY 
PERU 


KKKKKK 


Where arguments differ in rank by 1, the length 
of the axis of catenation is 1 plus the rank that 
that axis has in the higher-rank argument. 


If the function was lamination, the result has rank 
1 higher than the rank of the arguments. Each 
axis has the same length as in the arguments, and 
the new axis has length 2. 


X,;[1.5] Y 


Example of lamination: Suppose X and Y are 
the following 3-by-4 matrices of characters: 


X 
ITAL 
NORW 
PERU 


ROME 
OSLO 
LIMA 


There are three ways you could laminate this pair 
of rank-2 arrays: along a new axis located ahead 
of their first axis, after their last axis, or between 
their two existing axes. In 1-origin indexing, you 
could indicate those by indicating one of the fol- 
lowing axis numbers: 0.5 1.5 2.5. In O-origin, 
you'd choose one of 0.5 0.5 1.5. (The fraction 
doesn’t have to be .5; any value clearly distinct 
from the adjacent integers will do.) 


oX,[2.5] Y 
3 4 2 


X,{2.5] Y 
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If one of the arguments of lamination is a scalar, 
the scalar is treated as if it had the same rank and 
shape as the other argument. For example, if Y is 
the 3-by-4 array of characters as in the preceding 
example, and S is the scalar S«'*', laminating 
produces arrays as follows: 


X+Y The X take of Y 
X+Y The X drop of Y 


Right argument: Any array. The system accepts 
a scalar right argument as if it were a 1-element 
array having whatever rank is implied by the 
length of the left argument. 


Left argument: A numeric vector. The elements 
of X specify the length that you want in the result 
for each of the axes of Y. In general, the length 
of X must equal the rank of Y. 


The system treats a scalar X as if it were a 1- 
element vector. (This is one of the few cases in 
which a scalar is not extended to match the shape 
of the other argument.) 


Each element of X must be an integer. Each ele- 
ment of X may be positive, negative, or zero. 


Result: An array whose rank equals the length 
of the left argument. Except when you have a 


scalar right argument combined with a non-empty 
left argument, the result also has the same rank 
as Y. 


Each axis of the result is formed by taking (or 
dropping, depending on whether the function is + 


S,([1.5] Y 





or +) elements from each axis of Y. The amount 
taken (or dropped) is the absolute value of the 
corresponding element of X. The result has axes 
with lengths as follows: 


Shape resulting from take: |X 
Shape resulting from drop: Of (pY)-|X 


The sign of an element of X indicates whether it 
is from the beginning or from the end of the corre- 
sponding axis of Y that elements are to be taken 
(or dropped). A positive value means from the 
beginning, while a negative value means from the 
end. 


For example, suppose Y has two axes. Then the 
meaning of the following expressions is para- 
phrased to the right of each: 
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2 ` 54Y An array formed by taking from Y 
those elements in the first two rows 
and the last five columns. 


2  54Y An array formed by dropping from Y 


those elements in the first two rows 
and the last five columns. 


[Blc p]E [F 


result 














result 


result 








Taking more elements than exist in Y: You 
might include in X an element that indicates that 
you want to take from Y more elements than exist 
along that particular axis of Y. In that case, the 
additional positions in the result contain a “fill” 
value. The fill value is zero when Y is numeric, 
and blank when Y is character data. 


Where an element of X is positive, as many ele- 
ments as are available in Y are taken first, and 
then the fill value is used for the remainder. Thus, 
where an element of X is positive, in the result fill 
values (if any) appear at the end of that axis. 


} Where an element of Y is negative, elements are 


taken from the end of that axis of Y to become the 
end of the corresponding axis in the result. The 
fill value is used for the remaining positions at the 
front of that axis in the result. Thus, where an 
element of X is negative, in the result fill values 
(if any) appear at the front of that axis. 


Suppose Y is the following 3-by-4 matrix of num- 
bers: 


Then the expression 5 7+Y gives you a matrix 
with five rows and seven columns. The five rows 
are formed by taking the three existing rows of 
Y and then filling the remaining 2 positions with 
zeros. The seven columns are formed by taking the 
4 existing columns of Y and assigning them to the 
last 4 positions in the result, and filling the re- 
maining positions at the front with zeros. Thus: 


5 74+Y 


ooo 0 0 
oooo 0 
oo0o0 0 
O O uO OF 

b 

jo) 

= 

= 

a 

Y 


Take when the right argument is empty: 
When the left argument X calls for creation of an 
array that is not empty, but the right argument 
Y is empty, the result contains nothing but fill 
values. The result has the same internal type as 
the right argument. If the empty right argument 
is a character array, then the result consists of 
blanks. If the empty right argument is a numeric 
array, then the result consists of zeros. This result 
depends on the fact that, although in general the 
type of an empty array is not significant, neverthe- 
less, information regarding its type is retained, and 
does effect the result produced by take (and also 
by expand). 


Dropping more elements than an axis has: 

You might include in X an element whose absolute 
value is greater than the length of the correspond- 
ing axis of Y. That would mean dropping from 
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—s 


that axis more elements than it has. In the result, 
the length of that axis is zero. That is, the excess 
value in X has no effect. 


1Y Index generator; the first Y integers 


Argument: A numeric scalar. In principle, the 
argument should be a scalar. However, the system 
accepts a 1-element array of any rank as equiva- 
lent to a scalar. 


The value of the argument must be a non-negative 
integer. 


Result: A vector of integers. The length of the 
result is the value of Y. The result contains the 
first Y integers starting with the index origin, 
OT0. Thus, when DIO has the value 1, the expres- 
sion 17 gives you the vector 1 2 3 4 5 6 7, 
whereas when []JO has the value 0, the same 


expression gives you the vector O 1 2 3 4 5 6. 


The expression 10 (regardless of origin) gives you 
an empty numeric vector. 


The SHARP APL interpreter recognizes an 
expression in the form (BOOLEAN)/1pX and op- 
timizes its execution. When the Boolean vector is 
large but contains few ones, the expression is eval- 
uated even though the intermediate step 1pX im- 
plies a vector of consecutive integers that would 
require more space than may be available in the 
workspace. 


XiY The X index of Y 


Left argument: Any vector. No other rank is ac- 
ceptable for the left argument. 


Right argument: Any array. 


Result: An integer array of the same rank and 
shape as Y showing where in X the corresponding 
element of Y is found. 


The result is subject to the index origin DIO; when 
DIO is 1, an element of Y found in the first posi- 
tion of X is reported at position 1, whereas when 
DZO is O, it is reported at position 0. 


An element of the result is always the location of 
the first position within X at which is found an 
element equal to the corresponding element of. Y. 
If X contains repeated instances of certain values, 
the later occurrences have no effect upon the re- 
sult. This fact may be exploited in an expression 
that finds the nub of a vector (that is, the set of 
distinct values found within it). If Y is a vector, 
then its nub may be found by: 


((ipY)=YiY)/Y 


Where an element of the right argument Y is not 
found anywhere in the left argument X, the corre- 
sponding element of the result is assigned a value 
1 greater than the highest existing location in X. 
That value is [70+pX. A number and a character 
are never judged to be equal, so when one argu- 
ment is numeric while the other is character, no 
match is possible, and the result is 
(pY)pOI0+pX. 


Provided that all of the elements of Y are to be 
found somewhere in X, the following proposition 
is true (regardless of the type or rank of Y) 


X(X1.Y]=¥ 


Comparison tolerance with dyadic iota: The 
expression X.Y finds the first location in X at 
which each element of Y is found to be equal to 
an element of X. Where both arguments are 
numeric, it becomes necessary to decide whether 
they are equal to within comparison tolerance. 
Dyadic 1 is affected by [CT in the same way as 
=. For details, see the discussion with the defini- 
tions of equal and not equal. The effect can be 
summarized for a scalar Y by the following: 


XiY <> (X=Y)i1 


If you know in advance that you are dealing with 
data not subject to imprecisions of calculation or 
representation (so you are certain that you have 
no need of tolerant equality), you'll experience 
considerable gain in computing speed by setting 
OCT to zero before using dyadic iota. 
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XC¥1;Y2;Y3;...;¥n] Indexing: 
the Yth elements of X 
or X sub Y 


Indexing is unusual in two respects. First: the 
right argument is delimited by a pair of brackets. 
You could think of the left bracket [ as the pri- 
mary function symbol for indexing. The right 
bracket marks the end of the right argument of 
indexing, and in effect implies parentheses around 
the entire indexed expression; so that 


ALI] + B <+> (A[I]) +B 


Second: within brackets which enclose the right 
argument you write a list of expressions, separated 
by semicolons. (See the section entitled “A Note 
About Semicolons and Lists.” ) There’s a separate 
expression for each axis. It indicates the positions 
that are to be selected along that axis. 


Example: Suppose X is a vector. Since it has 
only one axis, it requires only one expression to 
specify the positions you want. That may be writ- 
ten: 


xLY] 


The array of indexes Y may be of any shape or 
rank, provided only that every one of its elements 
is a valid position within X. 


Suppose X is a matrix. Then you could select from 
it a sub-array by an expression such as 


XCY1;¥2] 


Because X has rank 2, there is one semicolon inside 
the brackets. It separates the expression Y1 (which 
shows positions to be selected along the first axis) 
from the expression Y2 (which shows positions to 
be selected along the second axis). 


Left argument: Any array having at least one 
axis. That is, an array other than a scalar. 


Right argument: A list of arrays, in general 
containing as many arrays as X has axes. The 
expressions that generate the various arrays are 
separated by semicolons. Since some indication is 
required for every axis of X, the number of semico- 
lons is always one less than the rank of X. 


A sequence of expressions separated by semicolons 
is called a list. A list is a way of referring to 
several arrays. The symbol ; is a separator, not 
a function. Writing Y1;Y2 does not form a single 
array from Y1 and Y2. There’s no way you can 
write a general expression such as X[Y] that will 
be valid regardless of the rank of X. In fact, 
XLY] is valid only when X is a vector (since it 
contains zero semicolons), and X[Y1;¥2] is valid 
only when X is a matrix (because it contains one 
semicolon), and so on. 


(If you need to write a program that can index 
an array of any rank, you have to either generate 
a character expression containing the right number 
of semicolons and then use @ to execute it, or else 
index it by referring always to the ravel of the 
array, exploiting an identity mentioned below.) 
For any axis which is to be retained unchanged 
in the result, no expression need be written, but 
the delimiting semicolons are still required. 










BRACKETS AND SEMICOLONS IN i] 




















ARRAY SELECTION BY INDEXING 
aray 
SCALAR name 
aray of 
sides aray element 
VECTOR name number(s) 
array array of 
sek oe array of row column 
MATRIN name numbers} number(s) 
C 3 ] 
atay of arras array of 
RANK-3 array plane of tow column 
ARRAY name numbers) numbers) number(s) 
C ; ; ] 
array of array of anay array of 
RANK-4 aray block plane ot row column 
ARRAY name number(s) number(s) number(s) number(s) 
C ; ; ; J 








The semicolon acts as a complete separator, so that 
the various expressions (even if they are com- 
pound expressions) do not have to be enclosed in 
parentheses. 


You can keep an axis just as it was in X by not 
selecting (i.e. not indexing) along that axis. You 
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do that by failing to specify any expression for that 
axis. Then that axis is reproduced unchanged in 
the result. But even if you write no expression for 
an axis, semicolons are still required. For exam- 
ple, if X has three axes, then X[Y1;Y2;] indicates 
that along the first axis, positions are to be selected 
by Y1, along the second axis by Y2, and the last 
axis is to be reproduced completely in the result. 
For a vector X, XL] +> X; similarly, for a matrix 
X, X03] +> X, and so on. Similarly, X[1 2;] se- 
lects positions 1 and 2 from the first axis and all 
positions from the second axis, and X[;1 2] se- 
lects all positions along the first axis, and positions 
1 and 2 of the second axis. 


Each array must be composed entirely of values 
which are valid indexes for that axis of X, taking 
into account the index origin DIO. Each element 
must therefore be an integer. 


Result: An array formed by selecting from X ele- 
ments at the positions indicated by the values in 
Y1, Y2, etc. 

















Expression to Select Individual Element 


Y[1;3;4] 


ER 

















result 





The shape of the result is determined solely by the 
shape of the arrays in the right argument. In the 
simple case when X is a vector, indexing can be 
written X[Y], and 


eX[Y] <> py 
More generally, this identity can be stated thus: 


pX[Y1;Y2; ... ;Yn] 
+> (p1), (p2), ... gp Pn 


Expressions to Extract Sub-Array 
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Notice that this means that wherever an axis is 
indexed by a scalar, the result has no axis. For 
example, when X is a matrix, X[1 3 5; 2] gives 
you a 3-element vector, whereas X[1 3 53,2] 
gives you a 3-by-1 matrix. 


The process of selection is a Cartesian product. 
The elements selected from X are those whose po- 
sitions are described by all possible combinations 
of the first-axis indexes mentioned in Y1 with the 
second-axis indexes mentioned in Y2, and so on for 
all the axes. 


If any of the selection arrays is present but is 
empty (for example X[Y1;Y2] when Y1 is an 
empty array), the result has length zero along that 
axis. 


X/Y X compressing Y 
X/Y X compressing the first axis of Y 


Compression shortens the length of one of the axes 
of Y according to values in the left argument X. 


Right argument: Any array. A scalar is treated 
as if it were a vector of the same length as the left 
argument. 


Left argument: A numeric vector or scalar each 
of whose elements are either 0 or 1. 


The length of X must be equal to the length of the 
axis of Y that’s being compressed. The left argu- 
ment may also be a scalar, in which case it is 
treated as if it were a vector of the appropriate 
length for the corresponding axis of Y. In practice, 
the left argument often arises as the result of some 
relational function on Y, so that the left argument 
is thereby a Boolean vector of the appropriate 
length. 


Axis of compression: Compression always takes 
place along just one axis. If you write X/Y, it’s 
along the last axis of Y. If you write XZY, it’s 
along the first axis of Y. 


Alternatively, you can indicate explicitly which 
axis you mean by using the axis operator. The 
axis operator appears as an expression enclosed in 
brackets immediately to the right of the / or the 
# symbol. When an axis is explicitly indicated, it 


makes no difference whether you use / or +. The 
value within the brackets must be a single element, 
and must indicate one of the axes of Y (taking into 
account the index origin OIO). Thus, the value 
must be an integer. 


Result: An array having the same type as Y, and 
the same rank, except that when Y is a scalar, the 
result is a vector. 


The axis of the result along which compression 
takes place retains those positions from Y in which 
the corresponding element of X is a 1, and lacks 
those positions where the corresponding element of 
X is 0. The various axes of the result have the 
same lengths as the corresponding axes of Y, ex- 
cept for the axis along which compression takes 
place. The length of that axis is +/X, or, when X 
is a scalar, either the length of that axis of Y 
(when X is 1), or zero (when X is 0). 


X\Y X expanding Y 
XXY X expanding the first axis of Y 


Expansion extends the length of one of the axes 
of Y according to values in the Boolean vector X. 


Right argument: Any array. A scalar is treated 
as if it were a vector of length +/X. 


Left argument: A numeric vector each of whose 
elements is either 0 or 1. 


The left argument X must be at least as long as 
the axis being expanded. It must contain as many 
1’s as the length of that axis. That is, the axis of 
Y along which expansion takes place must have 
length +/X. 


A scalar left argument is treated as if it were a 
1-element vector; this has the consequence that a 
left argument X whose value is a scalar 1 can only 
be used with a right argument in which the corre- 
sponding axis has length one, and an X whose 
value is a scalar 0 can only be used with a Y 
whose corresponding axis has length zero. 


Axis of expansion: Expansion always takes 
place along just one axis. If you write X\Y, it’s 
along the last axis of Y. If you write XXY, it’s 
along the first axis of Y. 
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Alternatively, you can indicate explicitly which 
axis you mean by using the axis operator. The 
axis operator appears as an expression enclosed in 
brackets immediately to the right of the \ or the 
\ symbol. When an axis is explicitly indicated, it 
makes no difference whether you use \ or X. The 
value within the brackets must be a single element, 
and must indicate one of the axes of Y (taking into 
account the index origin D70). Thus, the value 
must be an integer. 


Result: An array having the same type as Y, and 
the same rank, except that even when Y is a scalar, 
the result is a vector. 


In the result, the axis along which expansion took 
place contains all the positions that existed in the 
right argument. In addition, at each position corre- 
sponding to a 0 in the left argument, a new posi- 
tion is interpolated. 


The value that the system supplies at each interpo- 
lated position depends on the data type of the right 
argument—that is, whether it is numeric or char- 
acter data. When the argument (and, of course, 
the result) is numeric, the fill value is 0. When 


the argument is character data, the fill value is 
blank. 


It is possible to expand the right argument even 
when it’s an empty array. In that case, the left 
argument can’t contain any 1’s, but it may contain 
some 0’s. The result consists entirely of the fill 
value. To decide which fill value to use, the system 
consults the type of the right argument. In general, 
the type of an empty array isn’t important. An 
empty array has the same type as the array from 
which it was formed; for example 0p0 is an empty 
numeric array, whereas 0p'' is an empty charac- 
ter array. The type of an empty array becomes 
evident when the array is expanded; the result 
contains numeric 0’s if it was a numeric array, 
and blanks if it was a character array. 


AY Upgrade of Y 
YY Downgrade of Y 


Argument: Any numeric vector. 


Result: A permutation vector of the same length 
as Y, indicating the sequence in which you’d have 
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to take the elements of Y in order to arrange them 
in ascending order (when the function is 4) or in 
descending order (when the function is Y). A per- 
mutation vector is one that contains every member 
of .pY exactly once, in any order. 


To sort the elements of Y, you’d write 
YAY] or Y[YY] 


as appropriate. 


Where Y contains elements that are identical, AY 
and YY give you their positions in the order in 
which they are encountered in Y, that is, from left 
to right. 


Grade is not subject to DCT, so any difference at 
all between the elements of Y is significant in grad- 
ing—even a difference too small to be evident in 
a display unless QPP+18, or too small for = or # 
to distinguish them (when OCT isn’t zero). It is 
impossible to apply comparison tolerance to grad- 
ing because fuzzy inequality is not transitive, 
whereas 4 and Y depend on having a transitive 
relation between the elements being graded. 


Note that neither AY nor YY itself sorts Y; rather, 
each of them grades Y. That is, it specifies how 
Y should be indexed in order to sort it. There are 
several reasons why returning the grade of a vector 
is more useful than sorting it directly. For exam- 
ple, once you have the grade of Y, you can apply 
the result not to sort Y but to sort some other 
array. Suppose you have a matrix NAMES contain- 
ing the names of students, and a vector EXAM con- 
taining each student’s examination score. Then 
NAMES[YEXAM; ] gives you the names in descend- 
ing order of exam score. 


Inverse permutations: The expression AdAY 
gives you a permutation inverse to the one 
produced by AY. The inverse permutation is capa- 
ble of putting an array Y[AY] back into its origi- 
nal order. This can be expressed by the following 
identity: 


(YLAY])CAAY] <> Y 
In general, if P is a permutation vector, then 


AAP <> P and YYYYP + P 
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When the members of Y are all distinct, then 
AYY gives you the ranking of each of the elements, 
with the largest assigned to the first rank, while 
AAY gives you the ranking with the smallest as- 
signed to the first rank. 


Merge with grade: Grade may be used to merge 
elements from several different vectors. For exam- 
ple, suppose you have vectors A, B, and C; suppose 
that a vector M contains a map showing from 
which of the three arrays each position of the re- 
sult is to be taken. Where M has a 1, take from 
A, where M has a 2, take from B, and so on. Sup- 
pose also that M contains the correct number of 1s, 
2s, and so on. Then you get a single merged array 
by the following expression: 


(A,B,C)TAAM] 


If there are only two categories, then it’s possible 
(although not necessary) to represent the two ar- 
rays being merged by a Boolean vector. For exam- 
ple, if you want to apply a function called F1 to 
those elements of Y that don’t meet a particular 
test, but a function called F2 to those that do, then 
you could temporarily split Y into two arrays, 
apply the two functions to their respective argu- 
ments, and remerge, by an expession such as the 
following: 


( (F1 (~P)/Y), F2 P/Y)CAA4P) 


Grading matrices: To grade a matrix or any 
array of rank higher than 1, you must either re- 
peatedly grade by one column at a time (or row, 
etc., as appropriate), or apply some function such 
as 1 or +.x that reduces one axis to a single value 
to which A can be applied. 


Grading character data: To grade character 
data, you must find for each element a numeric 
value. That’s usually done by finding the position 
of the characters you have within a reference al- 
phabet. For example, to sort a matrix of characters 
into alphabetical order by rows, you'd find the 
numeric value of each element of Y by an expres- 
sion such as 


ALPHABET iY 


and then grade the resulting numeric array. 


In SHARP APL, the APL characters A-Z are in 
fact arranged in alphabetic order within DAV. 
However, alphabetizing Y by DAV1Y is not recom- 
mended: (a) because DAV is system-dependent, 
and (b) because it fails to include blanks, punctu- 
ation, or upper-case characters appropriately. Of 
course, sorting to detect duplicates (by making du- 
plicate values adjacent) can effectively make use 
of any reference alphabet, including DAV. 




















XeY Proposition: X is a member of Y 


This function is called “set membership.” It is also 
known by the name of the symbol, “epsilon.” Its 
result is equivalent to the “characteristic vector” 
in set notation. 


Right argument: Any array. 
Left argument: Any array. 


Result: A Boolean array having the same rank 
and shape as X. An element of the result is 1 
where the corresponding element of X exists any- 
where in Y, and 0 otherwise. 


Epsilon is subject to comparison tolerance, (CT, in 
the same way that = is. In fact, e and = are related 
by the following identity: 


XeY «+ Vv/Xo.=,Y 


For further discussion of the effect of comparison 
tolerance, see the chapter on comparison tolerance 
and the section entitled “Propositions on Equality 
and Inequality.” 


The function e is sometimes called “set member- 
ship.” It is the only one of the set functions imple- 
mented as an APL primitive. However, provided 
you are willing to work with a vector to represent 
the members of a set, intersection, union, and nub 
are readily obtained by definitions such as the fol- 
lowing: 


V ZeX INTERSECTION Y 
[1] Z«(XeY)/Y 
y 
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vV Z«X UNION Y 
[1] ZX, (~YeX) 


V Z<NUB Y; OCT 
[1] 0cT<-0 
[2] Z+((1pY)=Yi.Y)/Y+,Y 


XTY X encode Y; the X representation of Y 
X1Y X decode Y; the base value of Y 


These two functions deal with the explicit repre- 
sentations of numbers. You can use T to find the 
representation of a value, given the base in which 
you want it to appear. Conversely, you can use 
1 to find what value a representation has, given 
the base of the number system in which it’s writ- 
ten. For example, to express the value 100 as a 
4-digit base-8 number, you’d use 


8 8 8 8 T 100 
Oo 1 4 4 


and to find what value is represented in base-8 by 
the vector 1 4 4, you’d use 


81 144 
100 


For either function, the left argument X contains 
the radix (or perhaps several radixes). The radix 
describes the base—that is, the number system—in 
which a value is to be encoded, or from which a 
representation is to be decoded. 


An aside about the difference between a num- 
ber and its representation: There’s a funda- 
mental distinction—but one that’s easy to over- 
look—between the value of a number and its rep- 
resentation. It’s easy to confuse a number with its 
representation because whenever you see a number 
written, it has to appear in some representation. 
Usually, of course, numbers are written in the 
familiar decimal form. Nevertheless, that’s just one 
possible way of representing a number. 


A number exists and has a value quite apart from 
the way you choose to represent it. You may find 


it useful to think of a number as a point on the 
number line (or on the number plane, if you in- 
clude complex numbers). 


The value of a number is defined by its position. 
It has that position (i.e. that value) quite apart 
from how you choose to write about it. The year 
in which A Programming Language was pub- 
lished may be called 1962 or MCMLXII—but 
however that date is represented, it was the same 
point in time. 


Whenever you say just how much a particular 
number is, you have either to describe it by a 
procedure (for example, “that number which is 
the ratio of the circumference of a circle to its 
diameter”), or by a representation. Even the rep- 
resentation can be considered a procedure; “1962” 
means “the number you get by adding 1 thousand 
+ 9 hundreds + 6 tens + 2 units.” A phrase 
such as “a six-digit number” doesn’t refer directly 
to a number, but to its representation; it makes 
sense only if you understand it to be a shorthand 
for “a number whose conventional base-10 repre- 
sentation requires six numbers.” 


In the decimal system, by convention we limit the 
value that can occur in any position to a number 
that can be written with a single character. It’s 
called “base ten,” both because the value of the 
successive places differ from each other by a factor 
of ten, and because there are ten different symbols. 
That gives us an easy way to see the boundary of 
a number’s representation, since the various digits 
can then be written side by side, without any space 
between them. 


It’s important to keep in mind that this is simply 
a convention for convenience in writing. A repre- 
sentation in which each column could take on any 
value whatever would still make sense. In measur- 
ing time, we use a number system that has 60 
seconds in a minute, 60 minutes in an hour, 24 
hours in a day. But we don’t have 60 different 
symbols. We use the decimal representation, and 
permit seconds or minutes to take on any of the 
sixty values from 0 to 59. That requires some 
convention for separating the various components 
of the representation; often that’s done by writing 
a colon between them. Saying “the runner’s time 
was 37:28” is thus the decimal representation of 
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the base-sixty representation of the number of sec- 
onds it took. 


Notice that common number systems give you a 
way of writing the coefficients of a polynomial. 
The value of a 1 depends on the column it’s in. 
The values are the successive powers of the base. 
The rightmost column is BASEx0, the one to the 
left of it is BASE«*1, the one to the left of that 
is BASEx2, and so on. The base of a number 
system can be any number; it can even be negative, 
or fractional. But since the rightmost column al- 
ways has the value BASEx0, the last column is 
always the units column, regardless of the base. 


A number system doesn’t have to be just base-10 
or base-8, or any other single number. It’s possible 
to have what are called “mixed base” number sys- 
tems. Time has already been mentioned; it is mea- 
sured in base 24 60 60. Before Britain switched 
to the metric system, British weights and mea- 
sures—and even currency—abounded in mixed- 
base number systems. You can describe a mixed- 
base system by a vector of numbers showing the 
limit on the possible values in each column. For 
example, if time is represented by hours, minutes, 
and seconds, that could be described as base 
24 60 60. A single-base system such as decimal 
(base 10), binary (base 2), hexadecimal (base 
16), can be described by a vector in which all the 
elements are the same. A five-digit decimal repre- 
sentation is more fully described as being written 
in base 10 10 10 10 10. Once you think of the 
radix that way, both single-base and mixed-base 
systems use the same rule to determine the value 
of the successive positions. The rule is as follows: 


1. An entry in a column is usually limited to a 
number whose magnitude is smaller than the mag- 
nitude of the radix for that column. (Actually, this 
restriction isn’t essential; representations that vio- 
late it would still make sense. Moreover, if the 
first element of the radix is 0, that column can 
have any value.) 


2. The unit-value of a column is the product of 
the radix-elements further to the right of it. (No- 
tice that this implies that the last column, which 
has none further to the right, always has the value 
1. It also implies that the first element of the radix 
doesn’t affect the value of any column.) 


The argument and the result of encoding and 
decoding: Fundamentally, encoding is a process 
applied to a scalar value. For that scalar, you find 
a vector containing the various components of its 
representation. If you encode many values simulta- 
neously, it’s still a matter of finding a vector repre- 
sentation for each of them. If you use several dif- 
ferent radixes, then it’s a matter of finding several 
different vectors to represent each of the scalar 
values. 


Conversely, decoding is fundamentally finding the 
scalar value of a vector representation. If you 
simultaneously decode many different representa- 
tions, you produce a scalar value for each of them. 
If you use several different radixes, each vector 
representation is converted to several different val- 
ues, one for each radix. But it’s still a matter of 
finding a scalar value for a vector representation. 


Right argument of t: Any numeric array. The 
array contains (as scalars) the values whose ex- 
plicit representations you want to find. The result 
will contain one vector representation (or more, 
depending on the shape of the left argument) for 
each element of Y. 


Right argument of 1: Any numeric array. The 
first axis (and only the first axis) consists of the 
vector representations of numbers. One value (or 
more, depending on the shape of the left argu- 
ment) will be found for each of the vectors lying 
along the first axis. For example, suppose the 
right argument of 1 is a matrix having four rows 
and five columns, as follows: 


Y 


PHO Ww 
WOM NH 
POON 
H} 

oOorRr 
= 

Pwr oO 


You’d be finding what value is represented by the 
vector 3 7 2 1, and what value by the vector 
2 6 6 3, and so on. Each of those vectors is said 
to be arranged along the first axis, since (for ex- 
ample), the vector 3 7 2 1 consists of those ele- 
ments of Y that have differing positions on the first 
axis, but the same position on any other axes. 


Notice that if four of those vectors were arranged 
in a 4-by-2-by-2 array, the four elements 
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3 7 2 1 would still be spread along the first axis, 
but now the first axis would be planes: 


3 2 
2 1 
7 6 
O 1 
2 6 
0 10 
1 3 
1 9 


Left argument: A numeric array. The left argu- 
ment X describes the radix (or radixes) to be used 
in encoding or decoding the right argument Y. 
Where X is a vector, it describes the radix that is 
to be used either to generate a representation with 
T or to evaluate a representation with 1. When 
X has rank greater than 1, it is understood to be 
a set of vectors, describing several different radixes 
to be used independently. The way these radixes 
are arranged in a multi-axis array is explained 
below. 


Position values implied by a radix: The value 
of a particular element in a representation depends 
on its position. In the decimal system, the right- 
most position is the units position, the next is tens, 
then hundreds, and so on. The position values 
implied by a given radix can be generated by the 
function PV, defined for a vector RADIX as follows: 


V Z+PV RADIX 
[1] Z+140x\ORADIX ,1 
y 


Applied to a vector of seven 10s, PV shows that 
the rightmost column is units, and the seventh 
from the right is millions: 


PV 7p10 
1000000 100000 10000 1000 100 10 


Applied to a vector of four 16s, you get the first 
four position values of the hexadecimal system: 


PV 4p16 
4096 256 16 1 
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Applied to hours, minutes, and seconds, you get 
the number of seconds in 1 second, in a minute, 
and in an hour: 


PV 24 60 60 
3600 60 1 


Notice that the first element of the radix has no 
effect on the value of the first position. In fact, it 
can even be zero. 


PV 0 60 60 
3600 60 1 


There is some advantage in using 0 as the first 
element of a radix; see the paragraph headed 
“Completeness of a Representation.” 


Left argument of T or 1 having rank 2 or 
greater: When X has 2 or more axes, it contains 
several different radix vectors, each of which is to 
be used to generate or evaluate a representation. 
However, the representations are arranged differ- 
ently, depending upon whether the function is 1 
or T. 


With encode, each radix is arranged along the 
first axis of X. When X has rank 2 or higher, an 
expression such as XTY means that several differ- 
ent radixes will be used to generate several differ- 
ent representations for each element of Y. The po- 
sition values of a radix used as the left argument 
of encode can be described by the function 
PVAENC, as follows: 


V Z*+PVAENC RADIX; DIO; FIRST 
[1] D0<1 
[2] FIRST+(ppRADIX)+1 
[3] Z+FIRST+O[1]x\[1J6[1] RADIX,[1] 1 
V 


Applied to a 3-by-5 array each of whose elements 
is 10, the function shows five vectors of position 
values, each 100 10 1: 


PVAENC 3 5p10 

100 100 100 100 100 
10 10 10 10 10 
1 1 1 1 1 
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When the function is decode (i), each radix lies 
along the last axis of the left argument X. When 
X has rank 2 or higher, an expression such as 
X.Y means that the representations lying along the 
first axis of Y are to be evaluated according to each 
of several different radixes. Each radix vector is 
arranged along the last axis of X. The position 
values in a radix used with decode are described 
by the function PVADEC: 


V Z<PVADEC RADIX; FIRST 
[1] FIRST+«(-ppRADIX)+4 
[2] Z+FIRST+Ox\ORADIX,1 

y 


Applied to a 3-by-5 matrix each of whose elements 
is 10, the function produces 3 vectors of position 
values, each containing five elements: 


PVADEC 3 5p10 


10000 1000 100 10 ak 
10000 1000 100 10 s 
10000 1000 100 10 1 


These correspond to the three 5-element radixes 
within the matrix X. 


It’s important to notice that XiY is inverse to 
XTY only when the radix X is a vector. When X 
has rank 2 or greater, XTY gives you several differ- 
ent representations of the same element of Y, 
whereas, X1Y evaluates representations arranged 
along the first axis of Y according to each of sever- 
al different radixes. Even when X is a vector, the 
functions are not strictly inverse, since XTY may 
not completely represent Y. See the paragraph on 
“Completeness of a Representation.” 


Scalar radix: A scalar left argument of t gives 
you a scalar representation for each of the ele- 
ments of Y. The effect is identical to X |Y. 


A scalar left argument of 1 is treated as if it were 
a vector replicated to match the length of the first 
axis of Y. Watch out: An expression such as 
161A gives you the base-16 value of the represen- 
tations in A; but 167B does not give you the base- 
16 representation of the values in B. 


Result of XTY: A numeric array containing the 
representations of each of the elements of Y. Its 
rank is the sum of the ranks of the arguments, and 


its shape is (pX),oY. (The shape of the result of 
T is the same as the result of an outer product.) 
Within the result you get x/ 14pX explicit repre- 
sentations of each element of Y. Each representa- 
tion is as long as the last axis of X. The various 
representations occupy the first axes of the result. 


The fact that representations occupy the first axis 
of the result means that if X has rank one (so you 
get one representation for each element of Y) and 
Y also has rank one, then the result is a matrix 
in which the representations are arranged along 
the first axis (rows). Since each element of the 
result is in a different row, the representation of 
a particular element of Y occupies the correspond- 
ing column of the result. For example: 


own Fr 
oan or 


1 
7 
6 
5 
8 


eOON 
FOO Oo 


Definition of representation for a single value 
and a single radix: Since the various represen- 
tations are generated independently, the process 
can be described by stating an algorithm for the 
case when the radix X is a vector, and is applied 
to find the representation of a scalar Y. You could 
think of that process iteratively, as a procedure for 
finding, in turn, each of the numbers in the explic- 
it representation. Or it can also be stated as a 
parallel process. The following iterative definition 
finds the elements of the representation by starting 
at the right end (the units position) and working 
leftward. 


V Z+BASE REP N; I; NEXT; PV; OCT 


[1] Z+10CT+0 © I+{{l0+pBASE 
[2] PV+14+ox\OBASE , 1 
[3] TEST: +(QI0>I+I-1)to 
[4] NEXT+BASE[IJ|W:PV{I] 
[5] N<N-NEXTxPV[I] 
[6] Z+NEXT ,Z 
[7] >TEST 
v 


The following parallel version uses the variable 
ALREADY to show the portion of the value of N 
that’s already represented by the positions further 
to the right. 
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O 10 10 10 T 1776 1978 2001 7658 1 


V Z+BASE RP N; PV; ALREADY; (CT 
[1] OCT+o 
[2] PV+14+x\OBASE,1 
[3] ALREADY+( 14PV|N),0 
C4] Z+BASE | (N- ALREADY )+PV 


These definitions aren’t descriptions of the internal 
procedure the system uses; they aren’t intended to 
show you efficient algorithms for computation, but 
rather to help clarify some points about what hap- 
pens. For example, you can see that each element 
of the result is found as a residue of the corre- 
sponding element of the radix. That means that 
an element of the result must have a magnitude 
smaller than the magnitude of the corresponding 
element of the radix. However, when the first ele- 
ment of the radix is zero, then the first element 
of the result can be of any size. In that case, the 
first element of the result can always contain the 
entire value remaining after the portion already 
represented in the other elements. 


You can also see that for the rightmost position, 
the amount already represented is always zero. 
When the value being represented has a fractional 
component, the fraction always appears in the 
rightmost (units) position of the result. For exam- 
ple: 


10 10 10 10 107175.3 
0017 5.3 


You can use the fact that the units position always 
contains the fraction (if any) and that a position 
corresponding to a zero in the radix contains all 
the rest when you need to separate the integer and 
fractional components of a number. You do that 
by using the 0 1 representation. Having 1 as the 
last element of the radix assures that only the 
fractional part can appear in the last element of 
the result. Having 0 as the first element of the 
radix assures that the entire remainder will be 
included in that element of the result: 


O 1 T 175.3 
175 0.3 


Completeness of a representation: The result 
produced by T is a complete representation if, 
given the representation, the original value can be 
reconstructed. In that case (for a scalar Y) 
XiXTY +> Y. 


You can be sure that a radix is capable of produc- 
ing a complete representation of a number if the 
leftmost element of the radix is 0, or if the leftmost 
position value has the same sign and a greater 
magnitude than the number to be represented. 


When the column values all have a sign opposite 
to the sign of the value you’re representing, a com- 
plete representation is impossible. There’s no way 
you can use a positive radix to get a complete 
representation of a negative number (or to use a 
negative radix to get a complete representation of 
a positive number). Instead, you’ll get a comple- 
ment. For example: 


10 10 10 10 10 T 12 
9 9 9 8 8 


Complementary representations of negative values 
with a positive radix have the interesting property 
that, within the limit of the representation, addi- 
tion gives a usable result. For example, if 
BASE*10 10 10 10 10, then BASET 12 is 
9 9 9 8 8 while BASET36 is 0 0 O 3 6. Al- 
though 9 9 9 8 8 may not look like a familiar 
representation of 12, nevertheless the value of the 
sum of the two representations, taken modulo 
10*pBASE, is correct: 


(10*pBASE)|BASE19 9988+00036 


24 


Getting a complement as the result of representing 
a negative value with a positive radix applies 
equally to fractions. For example, compare the 
results in these two cases: 


O 1 T 175.3 
175 0.3 


O 1 T 175.3 
“176 0.7 


Conventional decimal notation represents separate- 
ly the sign and the magnitude. To represent a 
negative number Y in that fashion, you’d write: 


(xY) x BASET|Y 
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~w 


amne 


Result of 1: A numeric array, in which each 
element is the value of a representation that lies 
along the first axis of Y, decoded according to each 
of the radixes lying along the last axis of X. 


The rank of the result is the sum of the ranks of 
X and Y, less the one axis of X used for the radixes 
and the one axis of Y used for the representations. 
The shape of the result is (14pX), 14p¥. 


Decode follows the same conformability rules as 
inner product. That is, the length of the last axis 
of X (containing the radixes) must match the 
length of the first axis of Y (containing the repre- 
sentations). In fact, decode is equivalent to the 
inner product of the position values of the radixes 
with Y. If position values are defined by the func- 
tion PVADEC (introudced earlier) then 1 and +.x 
are related by the following identity: 


X1Y ++ (PVADEC X)+.xY 


When Y is a scalar, it is treated as though it were 
a vector having the same length as the last axis 
of X. The same thing happens when the first axis 
of Y has the length 1, but the last axis of X has 
some other length; that is, that axis of Y is treated 
as though it were extended to match the length of 
the last axis of X. That has the effect of finding 
the value of a number when each element of its 
representation has the same value. For example: 


10 10 1017 +> 10 10 10147 7 7 + 777 


Decode and the evaluation of polynomials: 

When X is a scalar, it is treated as if it were a 
vector matching in length the first axis of Y. Simi- 
larly, when the last axis of X has length one, it 
is treated as though it were extended to match the 
length of the first axis of Y. That has the same 
effect as a radix having the same value for each 
element, which implies that the position values are 
the successive powers of that value. Thus, whenev- 
er the left argument X is a scalar, or is an array 
whose last axis has length one, the expression 
X1Y evaluates a polynomial in X. The right argu- 
ment Y is an array of coefficients, with the various 
terms arranged along the first axis in descending 
order. (Descending order is the order commonly 
used in writing the coefficients used in number 


representation, although in algebra the reverse 
order is also in use for polynomials.) For example, 
suppose X is the 3-by-1 matrix formed by 
3 1p45 22.1 17, and Y is the following 4-by-5 
matrix: 


2.8 10.2 4.2 5.2 0.8 
Ties, 8.2 8.2 13.2 2.2 
5.2 11.2 4.8 3.8 5.2 
8.2 74.8 2.2 3.8 3.2 


Then you get a result in which five sets of polyno- 
mial coefficients (the columns of Y) are used to 
evaluate each of three values of X (the rows of 
X). The polynomials are respectively (in conven- 
tional notation): 

-2.8x? — 4.8x? + 5.2x +8.2 

10.2x3 + 8.2x? +11.2x —4.8 

4.2x3 + 8.2x? — 4.8x +2.2 

5.2x? +13.2x? — 3.8x -3.8 


-0.8x? + 2.2x? + 5.2x +3.2 





zy Matrix inverse of Y 
XBY X matrix-divide Y 














Introduction to matrix inverse and matrix divi- 
sion: The monadic and dyadic functions denoted 
by the symbol Ẹ (domino) concern the concept 
that in matrix algebra is called the inverse of a 
matrix. The inverse of a matrix Y is a matrix 
which, when matrix-multiplied by Y, gives the 
identity matrix (which is the matrix analogue of 
unity). In APL the notion of the inverse of a 
matrix is extended to matrix division and to the 
least-squares best fit for an over-determined ma- 
trix. 





The inverse of a matrix Y is defined as a matrix 
so constructed that when you post-multiply it by 
Y, you get the identity matrix. (Matrix multiplica- 
tion is not commutative, and so you have to distin- 
guish between pre-multiplying and post-multiply- 
ing.) In the conventional notation of matrix alge- 
bra, I stands for the identity matrix, a square 
matrix containing ones on the main diagonal and 
zeros elsewhere, and the inverse is indicated by the 
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superscript 1. So an inverse matrix is one that 
satisfies the equation which is stated (in conven- 
tional matrix notation) as follows: 


I=Y7Y 


In APL, matrix multiplication is indicated by the 
+.x inner product. So the inverse of a matrix is 
one that satisfies the following: 





I < (BY)+.xY 











In matrix algebra, an inverse is usually found only 
for a matrix that is square (that is, one that has 
the same number of rows as columns). In APL, 
matrix inverse is also defined for a matrix having 
more rows than columns. In that case, the shape 
of the inverse is the reverse of the shape of the 
matrix being inverted, and the identity 
I< (GY)+.xyY is still true. 














In practice, the inverse of a matrix, once ob- 
tained, is often multiplied by some other matrix. 
You often see expressions such as YX (which in 
APL notation is (HY)+.xX). In APL (although 
not in conventional matrix algebra) you can con- 
dense the two steps into a single function called 
matrix division. The matrix quotient XBY is linked 
to the inverse of a matrix by the following identity: 














XY <> (BY)+.xX 





You can use matrix division to solve systems of 
linear equations. The left argument X contains the 
constant terms, while the right argument Y is a 
matrix containing the coefficients for each of the 
unknowns. The various unknowns are arranged 
along the last axis (columns) of Y. To solve a set 
of equations in n unknowns, you have to have at 
least n independent equations. The various equa- 
tions are arranged along the first axis (rows) of 
Y. Since there must be at least as many equations 
as there are unknowns, Y must have at least as 
many rows as it has columns. 


Suppose you have the following set of four equa- 
tions in four unknowns, shown in conventional 
notation as follows: 


93 =12a+ b+4c+10d 
81 = -6a-5b+4c+ 7d 
93.5 = -4a + 9b + 3c+ 4d 
120.5 = -2a - 6b +7c+ 7d 


Represent this set of equations by a vector X con- 
taining the values of the constant terms, and a 
matrix Y containing the coefficients; thus: 


X 
93 81 93.5 120.5 


Y 


I I lIe 
NF ON 
nwo or 
Nort 
SF NO 


Then you get the values a, b, c, and d as the four 
elements of the result S: 


S<XEIY 
S 
“4 3 15.5 4 


To verify that this result really is the solution to 
this set of equations, check that Y+.xS (where S 
is the vector of solutions) is equal to the vector of 
constant terms X. 


Linear independence: If there are fewer equa- 
tions than there are unknowns, no general solution 
is possible. The right argument of [ may not have 
fewer rows than columns. 


Moreover, the rows of Y must be linearly indepen- 
dent. That is, for a system of equations in n un- 
knowns, there must be at least n independent 
rows. To make clear why this is essential, consider 
the following. Suppose you are asked to solve for 
x and y, given the two equations 


8 
8 


3x + 2y 
3x + 2y 


You should quite properly protest that these are 
the same equation, and you can’t find x and y 
with certainty until you have a second equation 
that is different. Suppose you are now given the 
pair 
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~“_ 


~~ 


8 = 3x + 2y 
16 6x + 4y 


You should again protest, because the second now 
is merely twice the first and not really any differ- 
ent. Notice also that the columns are multiples of 
each other, too. Column one is one and one-half 
times column two. 


Mathematicians have generalized this “really dif- 
ferent” requirement to express a condition for the 
solvability of any system of simultaneous linear 
equations or the invertibility of any matrix. The 
n equations in n unknowns must make n essential- 
ly different statements about the relationship of the 
coefficients; that is, the coefficients must be linear- 
ly independent. 


Sometimes it is hard to tell whether a set of coeffi- 
cients has this property of linear independence. 
For example, it is hard to tell offhand whether the 
following set of equations is linearly independent: 


3= 3x- y- 4 
-2 = -8x - 5y + 9z 
-4 = 2x+ 7y- z 


In fact, the second equation can be obtained from 
the first and third by multiplying them by -2 and 
-1, respectively, and adding: 


-6 = -6x + 2y + 8z 
4 = -2x - Ty + 2 


-2 = -8x - 5y + 9z 


There are two ways to find out whether a set of 
coefficients is linearly independent. The first is 
formally pretty, but not very useful, since there is 
no constructive way of utilizing it. It says that if 
vectors V or W can be found such that C+.xW or 
V+.xC is all zeros, then the matrix of coefficients 
C is linearly dependent and the system can’t be 
solved. The problem is that there is no easy way 
to find V or W before you’ve solved the linear sys- 
tem. 


The second way is to evaluate the determinant of 
the matrix of coefficients. If the determinant is 
zero, the coefficients are linearly dependent; the 
matrix has no inverse, and the linear system can’t 
be solved. If the determinant is non-zero, then the 


coefficients are linearly independent; the matrix 
has an inverse, and the linear. system can be 
solved. If the matrix of coefficients is overdeter- 
mined (that is, it has more rows than columns), 
then they are linearly independent if any square 
submatrix of the coefficients has a non-zero deter- 
minant. 


The determinant of a square matrix may be found 
by using the function DET in workspace 
25 MATRIXALG. 


The system rejects an argument that doesn’t meet 
that requirement as a DOMAIN ERROR. 


Alternatively, another approach is simply to go 
ahead with the argument Y, but after setting a 
value of [JTRAP which will detect a 
DOMAIN ERROR and halt work, report that no in- 
verse is possible, or take some other remedial ac- 
tion. To explore that alternative, see the chapter 
on event trapping. 


When a matrix barely meets the requirement that 
its columns be linearly independent, it is said to 
be “ill conditioned.” Very small changes in the 
values within such a matrix may produce large 
changes in the solution. If the data arise from 
observations that are subject to error, this may give 
you solutions which are quite unstable. 


Least-squares solution for over-determined sys- 
tems: If you have more equations than you have 
unknowns, the system of equations is said to be 
over-determined. In that case, the matrix Y con- 
taining the coefficients for the various unknowns 
has more rows than columns. If the rows are 
merely redundant, the solution is unchanged. But 
if the various rows are inconsistent with each 
other—as will usually be the case with data aris- 
ing from observations—no exact solution is possi- 
ble. In that case, the result of XAY gives you the 
best-fitting solution in the least-squares sense. If 
a perfect solution were possible, and you found the 
solution S by 





S + XBY 


then Y+.xS would give you back the constant term 
X exactly. The least-squares solution means that 
instead you get values for S chosen so as to mini- 
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mize the sum of the squares of the differences 
between your constants X and those estimated by 
Y+.xS. This least-squares solution is central to 
multiple linear regression, and also to polynomial 
curve fitting. Both of those procedures make use 
of data which, while subject to error, contain re- 
peated estimates of the same coefficient. The re- 
dundancy of repeated observations is used to offset 
the error in the individual data, and permit an 
approximate solution. 


Multiple linear regression requires a vector of de- 
pendent observations X and a matrix of indepen- 
dent or “predictor” observations Y. The matrix Y 
has a column for each of the independent varia- 
bles, and a row for each element of X. The coeffi- 
cients of the best-fitting linear combination of the 
independent variables are obtained from XBY. 


Finding a best-fitting polynomial is essentially the 
same procedure. In this case, there is a single inde- 
pendent variable, and the columns of Y consist of 
the vector of observations on that variable raised 
to the successive powers. Hence, to find the coeffi- 
cients of the best-fitting polynomial of degree n for 
the approximation of observations X from a “pre- 
dictor” variable P, you’d write 


XEIPo .*O(1N+1)-QI0 


The expression uses N+1 because you need the 
constant term (represented by Y*0) as well as 
Yx1 ... Y*N. 


Right argument of & A numeric matrix having 
at least as many rows as columns. A vector right 
argument is treated as though it were a 1-column 
matrix, and a scalar as a 1-by-1 matrix. 


The columns of Y must be linearly independent 
(as discussed in the paragraphs on linear indepen- 
dence). 


Left argument: A numeric array of rank 2 or 
less. The length of the first axis must be the same 
as the length of the first axis of the right argu- 
ment. 


Within the left argument X, the values of the con- 
stant terms (one for each row of Y) lie along the 
first axis. When there is a second axis, each col- 
umn of X contains a separate vector of constants 


for which a solution of the matrix equation will 
be found independently. 


Result of HY: A numeric array having the same 
rank as Y, and shape pY. The result contains the 
inverse of Y; that is, an array such that 
(BY)+.x¥ <> J. When Y is a matrix, I is the 
identity matrix (1C)o.=1C (where C is the num- 
ber of columns in Y). Where Y is a vector or a 
scalar, I is 1. 


Result of XBY: A numeric array calculated to 
meet the following criteria: 


When Y is a square matrix: 
(XBY)+.xY < X 

When Y has more rows than columns: 
+/+4(X-(XEY)+.x¥)*2 is a minimum 


Along the first axis of the result are arranged the 
coefficients corresponding to the columns of the 
right argument Y. 


Where the left argument is a matrix, the result is 
a matrix. Independent solutions are found for each 
column of X, and are returned as the columns of 
the result. 


The shape of the result is therefore as follows: its 
first axis has the same length as the last axis of 
Y (or 1, when Y is vector). Its second axis (if it 
has one) has the same length as the second axis 
of X. That can be stated in APL like this: 


pXEY <> ((ALppY)pi+(pY),1), 1+pX 


X+Y X specified by Y 


The left-pointing arrow assigns to the name X the 
value Y. The name to the left of the arrow may 
also be indexed; indexed assignment is described 
in the section following this one. 


Assignment is unlike other functions in one impor- 
tant respect. Its principal effect is to create a new 
variable, or to give a new value to an existing 
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variable. But strictly speaking, that is a side ef- 
fect, and not the result of the function. 


Right argument: Any data object (that is, array 
or package). 


Left argument: A name available for use as the 
name of a variable. 


Whether a name is available for use, and what use 
it already has, may depend on what functions—if 
any—are active at the time. To be available for 
use, the name appearing to the left of the + arrow 
can’t have any visible use as the name of a group, 
a function, or a label. (The class of use of a name 
is reported by the system function DNC.) 


Effect: The value Y is assigned to the name X. 


If the name X already had a visible use as the 
name of a variable, that previous value is lost. The 
name X now refers to the object (array or pack- 
age) generated by the expression to the right of 
the arrow. 


If the name X is available but is not in use, a 
variable is created having the name X. That name 
now refers to the object (array or package) gener- 
ated by the expression to the right of the arrow. 


Result: The result of assignment is the right ar- 
gument. 


Under some circumstances, the system does not 
display the result of assignment. When < is the 
root function of the statement in which it appears, 
its result is not displayed. The same rule applies 
also to + within the argument of ¢. See the discus- 


sion of “When the Result is Displayed.” 

The fact that the result of assignment is the same 
as its right argument makes possible multiple as- 
signment, for example statements such as this: 


A«B<C+Y 


or this: 


Warning: Respecifying the value of a variable 
which is also used elsewhere within the same 
statement may be dangerous. 


There’s nothing wrong with respecification where 
the sequence is unambiguous, for example in state- 
ments such as 


I+I+1 


But when the variable is used as well as re- 
specified in the same line, two problems arise: 


1. When the value of a variable is both respecified 
and used on the same line, and execution of the 
line is interrupted, resuming execution (which is 
necessarily at the beginning of the line) will no 
longer produce the same result. The following, 
while unambiguous, suffers from such a risk: 


DATA*«(pDATA) FORMAT DATA*CORRECTED DATA 


2. Certain expressions depend on the sequence in 
which the APL interpreter executes the statement. 
Statements such as 


(X+A+X) x (X*B+X) 


are subject to controversy about what the inter- 
preter should do and inconsistency about what it 
does do. If you want to join the discussion, you 
may find it interesting to experiment. But if you’re 
building function definitions for practical use, it is 
prudent to stay away from such ambiguities. 


X[A3...3C]+Y Indexed assignment: 
X sub A... C 


is specified by Y 


Indexed assignment is a special case of assignment. 
Most of what was said about assignment also ap- 
plies to indexed assignment. 


REPORT+ANALYZE DATA+EXTRACT DATES*PROMPT 'DATES?' 


or this, containing specifications embedded in the 
left argument: 


PROCESSED*VALID\ (VALID+VERIFY DATA)/DATA 
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Left argument: To the left of the specification 
arrow is a name X followed by brackets indicating 
indexing. That is the only permissible form for the 
left argument of indexed assignment: a name fol- 
lowed by brackets. You can not have any other 
sort of expression as a left argument. You can’t 
even have parentheses surrounding the name and 
its attendant brackets. 


The visible use of the name must refer to an array. 
If you attempt indexed specification of a variable 
that doesn’t yet exist, the system rejects it with the 
message VALUE ERROR. 


Indexes: Within the brackets, you must have a 
valid index expression, or a list of several such 
expressions, depending on the rank of X. The re- 
quirements for a valid list of indexes are discussed 
in detail in the section on “indexing.” 


An index is a list containing one expression for 
each axis of X. The expressions are separated by 
semicolons. The number of semicolons must be one 
less than the rank of X. If you attempt an expres- 
sion in which the number of semicolons is inap- 
propriate for the rank of X, the system rejects it 
with the message RANK ERROR. 


Each of the index expressions must contain values 
that are valid for the axis of X to which they’re 
applied, taking into account the index origin DZO 
and the length of that axis. If you attempt to use 
a value that is not a valid index, the system rejects 
it with the message INDEX ERROR. 


Right argument: An array having the same type 
(numeric or character) as X, and a shape consist- 
ent with the shape implied by the index expres- 
sions. However, if the implied shape is empty, it 
doesn’t matter what type the right argument is. 


The list of expressions inside the brackets implies 
the shape of the sub-array within X whose ele- 
ments are to be respecified. The implied shape can 
be calculated by catenating the shapes of the 
expressions used to index each axis. For example, 
if X has rank 3 and is indexed as X[A;B;C], the 
implied shape is (pA), (9B), (pC). Where index- 
ing is omitted for an axis, count instead the length 
that that axis already has in X. 


In shape, the array Y must match the shape im- 
plied by the indexing expressions. However, it 
isn’t necessary for Y to have the same rank as the 
implied shape. The shape of Y is acceptable if it 
matches the implied length of each axis that has 
a length other than 1. For example, if the implied 
shape is 2 3, then Y could have shape 2 3, or 
Y could have shape 1 2 3 or 21 3, or 
12113 1, and so on. Similarly, if the im- 
plied shape is 2 1 3, the shape of Y would be 
acceptable if it were 2 3, or 1 2 3, and so on. 


The axes of Y have to have the same lengths as 
the axes implied by the list of expressions within 
brackets. To simplify the discussion, call the list 
of index expressions I. However, axes of length 1 
(whether in Y or in I) have no effect; there can 
be any number of them in either I or Y, with no 
requirement that they correspond. But among the 
remaining axes, there must be the same number 
of axes in I and in Y, and the corresponding axes 
must have the same lengths. 


(1#pI)/pI <> (12pY)/pY 


When Y is a scalar, or a 1-element array of any 
rank, it is replicated to match the implied shape. 


Side effect: The indicated positions within X are 
assigned the values of the corresponding elements 
of Y. 


Watch out: If X is initially Boolean or integer, 
but Y contains elements that cannot be represented 
in that type, the entire array X is automatically 
converted to the internal type required to accom- 
modate the new elements. While this is ordinarily 
of no consequence, it may greatly increase the 
amount of space needed to store X. 


Result: The discussion of the result of assign- 
ment without indexing applies equally to indexed 
assignment. 


2Y Execute Y 


Argument: A character vector (or scalar). The 
characters in the right argument are taken as a 
line to be executed, and so they should constitute 
a valid statement, or a sequence of statements sep- 
arated by the character ©. 
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The argument of + may consist only of enterable 
characters; there’s a list of the 141 enterable char- 
acters in the section entitled “Listing of APL En- 
terable Characters.” Since you can’t use execute 
to invoke a system command or to open function 
definition mode, the first non-blank character 
shouldn’t be ), or [, or V or ¥. 


Effect: The array Y is executed, almost as it 
would be executed if it were a line within a de- 
fined function, or a line entered from the keyboard 
for immediate execution. There are three points of 
difference between a line supplied as the argument 
of ¢ and one encountered as a line of a defined 
function: 


1. You can’t use e to execute a system command, 
or to enter definition mode. 


2. The system lists ¢ in the state indicator, in the 
same way that it lists defined functions. (The sys- 
tem also does that with D, but doesn’t do it for a 
line entered from the keyboard during immediate 
execution mode.) When it puts ¢ in the state indi- 
cator, the system makes a corresponding entry in 
DZC to show a “line number” for it. It appends 
a O at the head of DEC. The line number for e 
(and also for D) is always 0. 


3. The meaning of a branch statement inside the 
line being executed depends upon the destination 
of the branch. 


A branch statement in the argument of 2: If 
the character vector Y that is the argument of 2 
contains a statement such as >ZABEL, it can mean 
either of two rather different things, depending on 
what value LABEL turns out to have. When 
LABEL is not empty and does not have the value 
O, the statement ¢'+ZABEL' causes the function 
that invoked 2 to go next to its line LABEL. 


But when the destination of the branch (in this 
example, the value of LABEL) turns out to be 
empty or to have the value 0, the branch is under- 
stood to refer not to the function that invoked ¢, 
but to the argument of ¢. Thus, within a statement 
being executed, +0 has the special meaning “Stop 
executing the argument of 2” and >10 has the 


special meaning “Go on executing the next state- 
ment within the argument of s.” 


It makes sense to use +0 or +10 only when the 
line to be executed contains several statements sep- 
arated by diamonds, and so the question of interest 
is whether or not to continue with executing the 
rest of the line. 


Once you’ve understood that +0 and +10 inside a 
line being executed with e refers to the line itself, 
it may come as a surprise to recall that +9 or 
+1E9 not only causes an end to execution of the 


| argument of ¢, but also causes the function that 


invoked 2 to branch to its line 9 (or 1£9) in the 
same way as it would if that statement had ap- 
peared directly as a line of the function’s defini- 
tion. 


Error messages with e: If the system encounters 
an error while it’s executing the line Y, it gives the 
usual diagnostic message (such as SYNTAX 
ERROR, RANK ERROR, etc.). Then it displays Y 
preceded by the symbol 2, with a caret pointing 
to the place within Y at which it ran into trouble. 


Result of 2Y: It is possible to write a statement 
such as the following: 


REPORT+ANALYZE "EXTRACT DATA' 


In that statement, the function ANALYZE is applied 
ta the result the system has calculated by executing 
the characters EXTRACT DATA. Whether ¢ returns 
a result will depend on how the function 
EXTRACT is defined. If EXTRACT returns a result, 
that result becomes the result of 2, and thereby 
becomes the argument of ANALYZE. But if 
EXTRACT doesn’t return a result, then e doesn’t 
return a result either (and the system will reject 
the entire statement with the message 
VALUE ERROR). 


Putting it more generally, the function Y returns 
a result if the statement contained in Y, when exe- 
cuted, returns a result. If the statement returns a 
result, then that result becomes the result of sY. 
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If the statement doesn’t return a result, then ¢Y 
has no result. When executing the argument of e 
returns no result, ¢ must be the root function (and 
hence, the first non-blank character) of the state- 
ment. 


When Y contains several statements separated by 
diamonds, the one whose result (or absence of 
result) is passed as the result of 2, is the statement 
last to be executed. 


Automatic display of the result of 2: When ¢ 
is the root function of a statement, the system 
decides whether to display the result by applying 
its usual rule not to the statement itself, but to the 
statement that is the argument of ¢. That rule is 
as follows: the system automatically displays a 
statement’s result (if there is one) except when 
the statement has a root function and the root 
function is <+ (“assignment”). 


Character representation 


You can convert numeric arrays to a character 
format (for example, for display) using ¥, or by 
using [FMT (described in the chapter on “System 
Functions for Representing and Converting Data.” 
The function ¥ is called “format,” or “thorn” 
(after its appearance, and to distinguish it from 
the other formatting primitive OFMT). Thorn exists 
in both monadic and dyadic forms, described sepa- 
rately in what follows. 


A useful effect of formatting a numeric array is 
that, since the result is a character array, you can 
Join to it other character arrays in order to produce 
a formatted table, or you can store the resulting 
array of characters as the value of a variable. 


Leading and trailing zeros: With both monadic 
and dyadic thorn, a leading zero is printed in the 
units position, but leading zeros don’t appear in 
any other position to the left of the decimal point. 


Trailing zeros to the right of the decimal point are 
always supplied by dyadic thorn, but never by 
monadic thorn. 


yY Character representation of Y 


Argument: Any array. 


Result: The representation of Y as a character 


farray. In general, the result has the same rank as 


Y, except that when Y is a scalar whose represen- 
tation takes more than one character, the result is 
a vector. 


Each axis of the result has the same length as the 
corresponding axis of Y, except for the last axis, 
whose length in the result is the sum of the widths 
of all the fields. 


The result contains the characters that would ap- 
pear in the system-default display of the right ar- 
gument Y. If you have a numeric array called Y, 
then 7Y gives you exactly the same characters that 
you would see at the terminal if you had simply 
typed Y. To the eye, the effect of the statement 


vY 
is just the same as 


Y 


(The output at the terminal looks exactly the same 
provided it fits within the maximum print width 
set at the terminal. The two displays might look 
different if the number of positions required to 
print them is greater than DPW. The system’s dis- 
play of a numeric array evoked by simply writing 
Y always ends a line at a blank, so that no num- 
ber’s representation appears partly on one line and 
partly on the next. The system doesn’t do that 
when it’s displaying character data, and hence 
doesn’t do it for the result of FY.) 


Significant digits controlled by (PP: When the 
system displays numeric data without specific for- 
mat instructions, the number of significant digits 
it displays is controlled by the system variable 
OPP (for “print precision”). The result of monad- 
ic format is affected in exactly the same way. For 
example, suppose Y is the 3-by-4 matrix formed 
by Y+3 4p+16. Then the display of Y and of ¥Y 
look just alike: 
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OPP 


10 
FY 
1 0.5 0.3333333333 
0.2 0.1666666667 1 
0.3333333333 0.25 0.2 
OPP<4 
yY 
1 0.5 0.3333 0.25 
0.2 0.1667 1 0.5 
0.3333 0.25 0.2 0.1667 


Result unaffected by DPW: The system variable 
OPW, print width, does not affect the result 
produced by monadic format (even though, as 
noted above, DPW may affect the way it appears 
at the terminal when you display it, just as it 
affects all output to the terminal). If you have a 
matrix Y that contains twenty separate columns of 
fractions, then the result of converting that array 
to characters may be far too wide to fit in the 
display area of a normal terminal. But that doesn’t 
affect the number of print positions it requires. 
For example: 


Y+3 20 p +160 


po FY 


3 340 

The foregoing example shows that, when DPP is 
10, it takes 340 print positions to format twenty 
columns of numbers. If you should now ask to 
have that formatted array displayed at the termi- 
nal, the long lines of output would still be broken 
up to fit in the display area, under the control of 
OPW, as usual. 


Monadic thorn applied to a character array: 
When you enter the statement +Y and Y is a 
character array already, the result is the same 
character array unchanged. 


Xty Character representation of Y in format 
X 


Right argument: Any numeric array. 


173 


0.25 
0.5 


0.1666666667 


ann 


Left argument: A numeric vector or a scalar. It 
specifies a format for each field of the result, cor- 
responding to a column of the right argument. 


The format of a field is described by a pair of 
numbers, so usually the length of X is twice the 
length of the last axis of Y. X may also be a single 
pair (or a scalar) describing a format for the re- 
sult as a whole. See also the discussion of “Num- 
ber of Control Pairs Required by Dyadic Thorn.” 


Control of width and digits: Within each pair, 
the two elements have significance as follows: 


1. Field width, w. This specifies the total width 
of a field in the result (including its leading 
blanks, if any). w may not be fractional and may 
not be negative. When w is 0, the system picks 
a field width sufficient to accommodate the actual 
values supplied in the right argument. 


2. Digits and format, d. The sign of d selects a 
format, and its magnitude controls the number of 


digits. 


Positive: Decimal format, with d positions to 
the right of the decimal 
Zero: Integer format 


Negative: 
cant digits 


Exponential format, with |w signifi- 


Number of control pairs required by dyadic 
thorn: The length of the left argument of dyadic 
y must meet one of the following conditions: 


1. One control pair for each column in the right 
argument. 


2. The number of control pairs on the left goes 
evenly into the number of columns on the right. 
In that case, the vector left argument is repeated 
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cyclically as many times as necessary to describe 
the columns on the right. Perhaps the simplest 
instance of this is a left argument consisting of a 
single control pair (that is, a vector of length 2) 
which applies to all the columns of the right argu- 
ment. 


3. There’s just one number (a scalar or a 1-ele- 
ment vector). That is treated in the same way as 
a single pair, with the first element of the pair 
being zero. 


Any other length for the left argument of y is 
rejected as a LENGTH ERROR. (The rules for the 
number of pairs in the left argument of ¥ are 
stricter than the rules for the number of phrases 
in the left argument of DFMT.) 


Result: A character array containing representa- 
tions of the values in the right argument X. The 
result has the same rank as X, except that when 
X is a scalar whose representation takes more than 
one character, the result is a vector. 


Each axis of the result has the same length as the 
corresponding axis of Y, except for the last axis, 
whose length is the sum of the widths of each of 
the fields. 


Example: Suppose X is the 3-by-3 matrix 
X<«3 3p+19. Without format instructions, the sys- 
tem would display it like this: 


T 0.5 0 . 3333333333 
0.25 0.2 0.1666666667 
0.1428571429 0.125 0.1111111111 


Suppose you have the following requirements for 
the display of X: 


Field 1: 5 characters wide, 0 decimals 
Field 2: 8 characters wide, 3 decimals 
Field 3: 5 characters wide, 2 decimals 


You can get that by using a left argument contain- 
ing three pairs, as follows: 


50 83 52%4X 


1 -250 -<14 
1 .200 .13 
0 -167 .11 


(Notice that where the representation must be 
truncated, it is rounded.) 


Field width 0 lets the system pick the width: 
When d is 0, the system determines how many 
spaces are needed to represent the data, while still 
leaving at least one leading blank in every field 
(including the first). (Monadic thorn, and dyadic 
thorn with 0 in the left argument, are the only 
uses of y that yield a result whose shape is not 
completely determined by the left argument.) 


Example: Suppose you have the following data 
table Y, with 3 rows and 3 columns: 


21 12345.6789 1.154444 
17 12345.6781 3.6789 
6 12345 2.665 


To print that table with 0 decimals for the first 
column, 3 decimals for the second columm, and 1 
decimal for the last column—but letting the system 
pick the field width—you specify: 


00 03 017 Y 
21 12345.679 1.2 
17 12345.678 3.7 
6 12345.000 2.7 


When several columns are controlled by a single 
pair of numbers from the left argument, the width 
the system picks is the one width required to ac- 
commodate all the numbers in all those columns; 
see the discussion of “One control pair applied to 
several columns.” 


Space for the negative sign: When a value is 
negative, space is required to write the negative 
sign in its representation. For example, if the ele- 
ment of Y in the first row and third column is 
negative, that column requires an additional print 
position: 


Y01;3]« -Y[1;3] 


00 03 0147Y 
21 12345.679 1.2 
17 12345.678 3.7 
6 12345.000 2.7 
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However, if the 6 down at the bottom left corner 
were 6, there would be no change in the spacing, 
since there is already room for its negative sign: 


Y(3;1]« -Y[3;1] 


00 03 0147Y 
21 12345.679 1.2 
17 12345.678 3.7 
T6 12345.000 2.7 


Selecting decimal or exponential form: When 
d is negative, the result appears in exponential 
format. The form selected applies to a particular 
column, so, although any one column must appear 
in the same format throughout, it’s possible to 
have one column of an array in decimal form and 
another in exponential form. 


Example: Suppose Y is an array which, without 
explicit formatting, the system would display thus: 


21 12345.6789 “4.2 
17 12345.6781 3.7 
“6 12345 2.7 


To show the second column in exponential form, 
with 8 significant digits, you’d enter: 


50 0 8 0177Y 
21 1.2345679E4 1.2 
17 1.2345678E4 3:7 
“6 1.2345000E4 2.7 
One control pair applied to several columns: 
When you want all columns formatted in the same 
way, a single control pair suffices. For example, 
if you want the array Y (shown in the preceding 
section) formatted so that every field has 15 print 
positions and 3 decimals, you can get it by: 


15 34 Y 
21.000 12345.679 
17.000 12345.678 
6.000 12345 .000 


Or with 15 print positions and no decimals: 


1507 Y 
21 12346 
17 12346 
6 12345 
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System-picked width for several columns: 
When you use a control pair whose first element 
is zero (or when you use a scalar), the system 
selects an appropriate width for that column or 
columns. 


When a single pair applies to several columns, 
then the width that the system picks is a single 
width applied to all the columns governed by that 
pair. The selected width is large enough to accom- 
modate all the numbers in all the columns to 
which the control pair applies. The width is 1 
greater than the number of characters required to 
print the number having the widest representation. 
The extra 1 assures you of at least one blank 
between adjacent fields. For example, that same 
array Y can be represented in decimal, with 2 
decimals in each field, like this: 


o27 Y (or alternatively 2 + Y) 
21.00 12345.68 71.15 
17.00 12345.68 3.68, 
76.00 12345.00 2.67 


and in exponential form, with 2 significant digits 
for each column, like this: 


o 277 (or alternatively 2 + Y) 
(-2.100F1 1.235F4 1.15420 
1.700E1 1.235E4 3.679E0 
~6.000F0 1.235E4 2.665E0 


1.154 
3.679 
2.665 


FR 
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Picking an appropriate field width to apply to 
all fields: Call the field width w and the num- 
ber of decimals d. To format X you’d write 


(wd) 7 X 


Suppose, to illustrate, we have a 4-by-3 matrix X 
whose values were established as follows: 


X < 4 3p *2x 6+112 


The display of a column of numbers appears with 
the units positions aligned; since the decimal posi- 
tions are always filled, there are always characters 
out to the right edge of each field. The last d 
columns contain the digits to the right of the deci- 
mal place. When d is zero, then there are no 
decimal places (that is, the numbers are displayed 
to the nearest integer) and no decimal point. 


55 403 
22026 162755 





When d is greater than zero, the last d columns 
contain the decimal digits, and the next column 
leftward contains a decimal point on every line. 


Since both the decimal places and the point are 
coming out of the total field width w, w must be 
greater than d (except, of course, for the special 
case in which w is zero). 


In the part of the field to the left of the decimal 
point, you need enough space to write the integer 





12 4 F X 


_——_—w — aW OW H 


<d—> <d—> <J—» 


-0000 -0003 -0025 
-0183 -1353 1.0000 
7.3891 54.5982 403.4288 
2980.9580 22026.4658 162754.7914 


portion of the number having the largest magni- 
tude in that column. You also need an additional 
column in which to put the negative sign for a 
value that’s negative. 


12 4 F -X 
.0000 —.0003 ~.0025 
~.0183 is 1353 1.0000 
7.3891 54.5982 403.4288 


2980.9580 22026.4658 162754.7914 


Unless you really want the adjacent fields printed 
right up against each other without separation (as 
they appear in the last row of the preceding exam- 
ple) you should make w at least 1 greater than 
the total space needed for your widest number. 
The unused space in the field appears as blanks 
at the left of each field (including at the left of 
the very first field). 


If you want the system to figure out the field 
width for each column independently, you need a 
left argument containing a pair of numbers for 
each column on the right, chosen so that the first 
member of each pair is zero. That allows a wide 
field for a column that contains a number whose 
representation is wide, and a narrow field for one 
that doesn’t. 


Common width for all columns: 
—_— EE 


O 4 y OY 


2980.9580 
54.5982 22026.4658 
403.4288 162754.7914 


-0000 .0183 7.3891 


-0003 -1353 
-0025 1.0000 
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Width set separately for each column: 


a LE 


O4 O04 O04 O4 FY 


.0000 .0183 7.3891 2980.9580 
.0003 .1353 54.5982 22026.4658 
.0025 1.0000 403.4288 162754.7914 





Exponential form: When a pair’s second ele- 
ment d is negative, the corresponding field of the 
result is in exponential form. When you express 
a number in exponential form, in effect you shift 
the decimal point until the number (whatever its 
original size) can be written with just one digit 
to the left of the decimal point. Then you show 
the power of 10 by which that number would have 
to be multiplied to give you the correct value. An 
exponential representation of the number 7.3 mil- 
lion is 7.36, and 73 million appears as 7.37. 
Avogadro’s number is 6.0228223. 


The scaled-down portion of the representation, 
having a value of at least 1 and less than 10, is 
called the mantissa. The power of ten by which 
the mantissa must be multiplied is called the ex- 
ponent (or sometimes the characteristic). Immedi- 
ately to the right of the mantissa, a letter Æ (for 
exponent) appears, followed by the digits that rep- 
resent the exponent. 


A very small number takes a negative exponent. 
For example, the mass of an electron (in grams) 
appears in exponential form as 9.10662 28. 


The sign of the exponent is independent of the 
sign of the number itself. As usual, a negative 
number is indicated by the presence of a negative 
sign as the very first non-blank character. Thus, 
a very small negative number may have two nega- 
tive signs in its exponential representation: one for 
itself (at the beginning), and one for its exponent 
(right after the £). The charge of an electron, 
when displayed, appears as 1.5921K 20. 


There’s one number that can’t be written so that 
its mantissa is between 1 and 10. That number 
is zero. By convention, in exponential form, zero 
is written OFO (or, if you ask for two decimals) 
0.00Ẹ£0. 


Significant digits in exponential form: When 
the second element of a pair in the left argument 


X is negative, the absolute value of d controls the 
number of significant digits (rather than the num- 
ber of decimal digits). “Significant digits” includes 
both the one digit appearing to the left of the point 
and those that come after. For example, if M is still 
the mass of an electron, then formatting it in a 
field 12 print positions wide, with 4 significant 
digits, appears like this: 


12 47M 
9.107E 28 


Or with the same field width and 6 significant 
digits: 


12 674M 
9.10660E 28 


Alignment of exponential representation: Ina 
display organized into columns (that is, display of 
an array of rank 2 or greater), both the decimal 
points and the £’s are aligned. Since the exponents 
appear immediately to the right of the £’s, but 
may differ in width, they may not extend all the 
way to the right edge of the field. 


Minimum field width for exponential form: 
To be sure that the result can be written in the 
space allowed, the field width must be at least 6 
greater than the number of digits requested. To 
be sure of having a blank at the beginning of each 
field, you need a width 7 greater than the number 
of digits. Provided you know that none of your 
numbers will be negative, the absolute minimum 
you can get away with is a width 5 greater than 
the number of digits. 


Decimal and exponential fields in the same dis- 
play: It may be that in one pair the second ele- 
ment is positive, while in another pair the second 
element is negative. In that case, one column ap- 
pears in decimal form and the other in exponen- 
tial. Here again is the array Y displayed (without 
explicit formatting) like this: 


21 12345.6789 71.154444 
17 12345.6781 3.6789 
“6 12345 2.665 


Suppose you need to display Y according to the 
following scheme. The width of each field is to be 
12. The first column is to be represented in expo- 
nential form with 3 significant digits. The second 
column is to be represented in exponential form 
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with 6 digits. The last column is to be represented 
in decimal form with 5 decimals: 


12 3 125 1257Y 


2.100071 1.234568F4 “1.15444 
_1.7000F1 1.234568E4 3.67890 
6.0000FO 1.234500F4 2.66500 


Insufficient space in either form 


If you request the character form of a numeric 
array (either decimal or exponential) but specify 
a field too narrow to contain it, the representation 
of each number that won’t fit is replaced by aster- 
isks across the full width of the field. 


Y <- 2 1p 1 1 x 10:3 


10 “4 ry 
_3.33333E0 
3.33333E0 


9 4 PY 
3.33333E0 
KaAKKKKKKEK 


The second row can’t be represented because there 
isn’t room for the negative sign. 


If you request more digits than the system is capa- 
ble of providing (18 is the greatest feasible preci- 
sion), the additional positions are filled with zeros. 


X?Y Deal X from Y 


Arguments: Each argument is a single non-neg- 
ative integer not greater than 1+2%*31 (that is, 
2147483647). Each must be a single element, but 
may be of any rank. The left argument X may not 
be greater than the right argument Y. 


Result: A numeric vector of length X, containing 
X distinct integers selected randomly, without re- 
placement, from the set 1Y. When the left argu- 
ment has the same value as the right argument 
(for example, in Y?Y) the result is a random per- 
mutation of Y. 


The values returned by dyadic ? are selected by 
a pseudo-random process. That is, although the 
selection meets most tests of randomness, it is the 
product of a repeatable procedure that depends on 
the value of the system variable DRL. The system 


uses two different procedures to evaluate X?Y; 
their results differ. Each algorithm makes use of 
the mechanism used to evaluate monadic ?; see the 
discussion of the function “roll.” In the definitions 
that follow, the use of “roll” in evaluating “deal” 
is represented by the function DROLL. 


The first algorithm simply calls DROLL repeatedly. 
If a value proposed by DROLL has already been 
used, the interpreter discards it and tries another, 
continuing in that fashion until it has generated 
X distinct values: 


V RX DEAL1 Y; Q 
[1] R+i0 
[2] TEST: +(X=pR)/0 
[3] ROLL: Q+«DROLL Y 
[4] ReR, (~QeR)/Q 
[5] >TEST 

y 


In the preceding function, the number of times 
DROLL is called is at least X, but may be greater. 
As X increases, the algorithm requires more time. 
That’s because, for each new element, the system 
must check through all the elements already gener- 
ated. Whenever X is relatively large (greater than 
LY+16) and the workspace has room to store all 
the integers 1Y, the system substitutes the follow- 
ing algorithm, which successively exchanges the 
values in the first X positions of 1Y with others 
selected at random: 


V ReX DEAL? Y; I; Q 


[1] I+0 © Rebiy 
[2] TEST: +(X<I+I+1)/END 
[3] Q&e-(I--~I0),(I-1)+DROLL Y-I-1 
[4] R(Q]+R[ OQ] 
[5] >TEST 
[6] END: R<X+R 
y 


The function DROLL generates a random integer. 
It uses the constants P and M described in the 
discussion of roll, and affects DRL in the same way 
as roll. Its result may differ from the result of 
monadic ? because the divisor is P+1 rather than 
P. 


V ReDROLL Y; OCT 


[1] OCT<o 
[2] ORL+P | MxDORL 
[3] R4JT0+LYxORL:P+1 
; > 
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Chapter 18: 


BRANCH 
STATEMENTS 





BRANCH STATEMENTS 


A statement whose first non-blank character is the 
right arrow > is a branch statement. It is used: 


1. to direct the sequence in which statements. are 
executed within a function; 


2. to exit from a function; 


3. to resume execution of a suspended function 
from a trap line or from immediate execution; 


4, to abort execution of all functions initiated by 
the last keyboard entry or by execution of the 
latent expression. 


Form of branch statement: The branch arrow 
> may stand alone or may be followed by an 
expression. An arrow with no expression following 
it is referred to as a “naked” branch. 


Destination of a branch 


The value of the expression to the right of the > 
is the branch’s destination. When evaluated, the 
destination must be, a numeric scalar or vector 
whose first element (if it exists) is an integer; 
otherwise the system rejects the statement with the 
message DOMAIN ERROR. 


The destination identifies a line within the current 
function. That line is the one that will be executed 
next. 


The expression to the right of the arrow is usually 
stated as some function on one or more of the 
function’s line labels. However, the statement isn’t 
required to refer to a label. When it evaluates a 
destination statement, the system supplies for each 
label its current numeric value, which is the num- 
ber of the line to which the label is attached. 


Result of branch: Branch is not a function, and 
does not have a result. 


Effect when destination is neither zero nor 
empty: Control passes immediately to the line 
identified by the first element of the destination. 


When the branch statement occurred in a trap line 
or was entered from the keyboard, execution of the 
most-recently suspended function resumes at the 
indicated line. When execution has been halted 
(for example, by an untrapped error or interrupt), 
this gives you a way to resume execution, by enter- 
ing from the keyboard an instruction such as 
DLC. 


When the destination is not the number of a line 
in the current function, execution of the current 
function is ended, and control passes to the func- 
tion that invoked it. 


The statements in the two preceding paragraphs 
are true regardless of where the branch statement 
is located within the line, or whether it occurs 
within the argument of the execute function ¢. 


Watch out: When you have control at the key- 
board, but there’s a suspended function on the 
state indicator and there’s an active (TRAP, an 
invalid instruction that you enter from the key- 
board may be trapped. If the trap line contains a 
branch, execution of the suspended function will 
resume. 


Effect when destination is zero: Execution of 
the current function is terminated, and control 
passes to the function that invoked it. This is true 
regardless of whether the branch statement is part 
of the function being executed, is part of a trap 
line, or is part of a line entered from the keyboard 
for immediate execution. However, if the branch 
statement is within the argument of 2, it is under- 
stood to refer only to the execute function itself. 
Thus, ¢'+0 © FOO' terminates the use of ¢ (so 
that FOO is not executed), but has no effect on the 
execution of the current function. 


Effect when destination is empty: Branch to 
an empty vector causes execution to continue in 
sequence. 


When the branch statement has a diamond to the 
right of it, execution continues with the next state- 
ment on the line. (That’s true even when the next 
statement is empty.) 


Watch out: When a branch with an empty des- 
tination and another statement to the right of it 
(such as +EMPTY © FOO) occurs in a trap line or 
is entered from the keyboard, the branch has no 
effect on the suspended function. 


Watch out: When a branch with an empty des- 
tination and no other statement to the right of it 
occurs in a trap line or is entered from the key- 
board, execution resumes at the next line in se- 
quence. That is, at DZC+1 rather than at DZC. 


Effect of naked branch: Execution of the func- 
tion now being executed, and of the entire se- 
quence of functions that invoked it, is aborted. The 
system removes from the state indicator the current 
top row (containing the name of the function now 
being executed); the system also removes from the 
state indicator all rows down to (but not includ- 
ing) the next row that is marked with an asterisk 
(indicating a suspended function). 


Effect of branch during Q input: A naked 
branch within [J input acts in the same way as a 
naked branch during execution. That is, the evalu- 
ation of [] is aborted, and so is the sequence of 
functions (if any) that invoked [. 


Branch with a destination is not permitted during 
D input. If you attempt it, the system rejects your 
entry with the message SYNTAX ERROR and then 
reissues the request for 0 input. 


Common forms of branching 


The line that is next to be executed depends on 
the value of the destination, not the manner in 
which it is calculated. So there’s a limitless fund 
of ways to write branch expressions. The follow- 
ing examples illustrate only a very few of the pos- 
sibilities. 


Conditional branch: The destination expression 
includes a label and a test; the result is either 
empty (no branch) or the value of the label. The 
test yields either a 1 (condition is true) or a 0 
(condition is false). The result of the test is used 
to select or deselect the value of the label, using 
compression, reshape, take, or drop. For example, 
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to branch to LABEL when A is greater than B could 
be written: 


+(A>B)/LABEL 


A complementary pair corresponding to “if” and 
“unless” can be formed using + for “if? and + for 
“unless”: 


>(A>B)tLABEL 
Branch to LABEL if A>B 


+(ASB)+LABEL 
Branch to LABEL unless A<B 


Conditional execution of statements on the 
same line: If you want to execute WORK only 
when A is greater than B, you could use branch 
to exit conditionally from the line, thereby execut- 
ing WORK only when the destination is empty: 


>(ASB)/QLC+1 © WORK 


Multi-way branch: Compression or indexing 
may be used to select from among any number of 
alternatives. For example: 


>((TEST1, TEST2, TEST3)/LABEL1, LABEL2, LABEL3) , DEFAULT 
or 
+(LABEL1, LABEL2, LABEL3)(TEST] 


Iteration: A simple loop usually combines a con- 
ditional branch and an unconditional branch. The 
following shows a leading decision that controls 
N repetitions of a step called WORK. It is called a 
“leading” decision because the test is made before 
WORK has ever been executed (thereby allowing for 
the possibility that WORK is executed zero times): 


I+0 

TEST: +(N<I+I+1)/NEXT 
WORK 
>TEST 

NEXT: 


t% 
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Chapter 19: 


MONADIC 
OPERATORS 





f\Y f Scan of Y 
f\Y f First-axis scan of Y 


Argument: Any dyadic scalar primitive function. 
(Note that the argument of an operator is the 
primitive function appearing immediately to the 
left of it.) 


Result: A derived function. The derived function 
takes its name from the function that is the left 
argument, followed by the word “scan.” For ex- 
ample, the result of +\ is the derived function 
“plus scan.” 


Axis along which the derived function scans: 
The derived function scans ‘along one axis of its 
argument. Unless the derived function is modified 
by the axis operator, f\ denotes scan along the last 
axis, while fX denotes scan along the first axis. 


By using the axis operator, you may indicate ex- 
plicitly any one of the argument’s existing axes. 
When you use the axis operator, it makes no dif- 
ference whether you use \ or \ to denote the scan 
operator. 


Domain of the derived scan function: Any 
array whose elements would be acceptable as ar- 
guments of the function f. For example, +\ accepts 
as an argument any array for which the successive 
pairs generated during summation are acceptable 
arguments of dyadic +. Note that whether a partic- 
ular array is a valid argument may depend on the 
sequence of particular values along an axis, or the 
length of the axis. 


If the axis over which scanning takes place has 
length 1 or 0, the argument is always acceptable. 


Result of the derived scan function: An array 
having the same rank and shape as the argument. 


Each element of the result is computed by suc- 
cessively applying the argument function along 
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that axis. For example, in the result of +\Y, the 
second position along the last axis contains the 
sum of the first two positions along the last axis 
of Y. Similarly, the third position of the result 
contains the sum of the first three positions in the 
argument, the fourth the sum of the first four, and 
so on. 


Suppose Y is the following 3-by-4 array: 


Y 
1 2 3 4 
5 6 7 8 
9 10 11 12 


Then +\Y yields an array of the same shape, con- 
taining the successive sums over Y’s last axis (col- 
umns): 


+\Y 
1 3 6 10 
5 11 18 26 
9 19 30 42 


The first position along the last axis always con- 
tains the same values as the corresponding position 
in the argument. The system even permits this 
rule to ‘provide a result for the first position of an 
array that would otherwise be outside the domain 
of the argument function. For example: 


Z3 409112 
A\Z 
DOMAIN ERROR 
A\Z 
A 
A\3 114Z 
1 
5 
9 


Order of execution in scans: The value at each 
position of the result is formed by repeatedly ap- 
plying the function f over all the positions up to 
it. That can be made clear in the following dia- 
gram, which shows how the seven elements of the 
result are formed in calculating +\17: 
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6 
6 


+ 
+6+7 


In similar fashion, the steps in forming the result 
of -\17 can be illustrated as follows: 





Clearly, calculating the value of the third position 
of the result involves two uses of the function f, 
the fourth position requires three uses of f, and 
so on. The order in which those are executed af- 
fects the results in two ways: 


1. In principle, the answer to the question “does 
order matter?” should depend only on whether the 
function is associative. A function f is said to be 
associative if, for any values of A, B, and C, 


(AfB)fC — Af (BEC) 


Addition is associative, and so (1+2)+3 is equiva- 
lent to 1+(2+3). Subtraction is not associative, 
and so 1-(2-3) isn’t equivalent to (1-2)-3. 


2. In practice, imprecisions introduced by the way 
the system represents numbers mean that, even for 
associative functions, order of execution may inter- 
act with the location of particular extreme values 
within the array. 


Order of execution for non-associative func- 
tions: The system treats the successive positions 
within the array in the same way as successive 
variables in an expression such as A~B-C. That is, 
each function applies to the entire expression to 
the right of it, and thus the functions must be 
evaluated from right to left. 


Repeating the example used earlier, the steps in 
computing the result of -\17 are shown below, 
with parentheses to make explicit the order of exe- 
cution: 


E2 
41 -(2 - 3) 
-(2 -(3 - 4)) 
-(2 -(3 -(4 = 5))) 
-(2 -(3 -(4 -(5 - 6)))) 
-(2 -(3 -(4 -(5 -(6 - 7))))) 


See also the discussion of reduction by non-associa- 
tive functions in the section on “reduce.” 


Order of execution for associative functions: In 
principle, the system uses the same order of execu- 
tion for all functions, without considering whether 
the function is or is not associative. But for asso- 
ciative functions, the order shouldn’t matter, and 
the system can compute the partial sums consider- 
ably faster if it works across the array from left 
to right rather than from right to left. For this 
reason, the SHARP APL system evaluates the 
scan of an associative function from left to right 
rather than from right to left. For plus scan, this 
can be made explicit by the following diagram: 


1 
(1 2)+ 3 
((1 2)+ 3)+ 4 
(((1 2)+ 3)+ 4)+ 5 
C(((1 + 2)+ 3)+ 4)+ 5)+ 6 
(((((1 2)+ 3)+ 4)+ 5)+ 6)+ 7 








In most applications, you won’t see any effect of 
this computational shortcut. However, order of ex- 
ecution may make a difference to the result of a 
scan (or reduction) using + or x if your particular 
data generate partial results that are beyond the 
system’s ability to represent numbers precisely. 
For + and x only, it may be useful to be aware 
that associative functions are executed from left to 
right. 


The way in which order of execution might affect 
a result can be illustrated as follows. Consider the 
vector Z with the following values: 


Z 
1E40 “1F40 1 


If you compute the sum of the first two elements, 
1840 and “4240 exactly cancel each other, so the 
second element of the result is 0. Then adding 1 
to that gives you 1 as the third element of the 
result. That’s the result the system in fact returns: 


+\ 1E40 “1Fu0 1 
1E40 0 1 


But that result depends on the fact that the system 
finds the sum of the first two elements before it 
adds the third. Suppose the elements were ar- 
ranged in a different order; for example, as they 
are in W: 


W 
1 1F40 1F 40 


Then the system would first add 1 and 1240. It 
isn’t able to represent numbers with enough preci- 
sion to distinguish between 1£40 and 1-more- 
than-1£40, and so the result is reported as follows: 


+\1 1F40 “140 
1 1£40 0 
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Some useful scans: The following examples 
suggest some applications of scans. The argument 
N indicates any numeric array, while B indicates 
a Boolean array. 











Cumulative sum of Y. 





x\Y Cumulative product of N (for example, over 
successive rates of growth or attrition). 


Cumulative “highwater” of N. 
All Os after the first 0 in B. 
All 1s after the first 1 in B. 
1 at the first 1 in B. 


0 at the first O in B. 





z\B Consecutive 1s or Os, reversing at each 1 in 
B. 


f/y f Reduce of Y 
f/y f First-axis reduce of Y 


Argument: Any dyadic scalar primitive function. 
(Note that the argument of an operator is the 
primitive function appearing immediately to the 
left of it.) 


Result: A derived function. The derived function 
takes its name from the function that is the left 
argument, followed by the word “reduce.” For ex- 
ample, the result of +/ is “plus reduce.” 


Certain commonly-used reductions are also infor- 
mally known by names derived from the way they 
are used. For example, [ /Y may be called “maxi- 
mum of Y,” +/Y may be called “sum of Y,” and 
x/Y may be called “product of y.” In similar fash- 
ion, for a Boolean array B, #/B may be called 
“parity of B,’ A/Y may be called “all B,’ while 
v/B may be called “any B.” 


aa 
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Axis along which the derived function reduces: 
The derived function reduces along one axis of its 
argument. Unless the derived function is modified 
by the axis operator, f/ denotes reduction along 
the last axis, while fZ denotes reduction along the 
first axis. 


By using the axis operator, you may indicate ex- 
plicitly any one of the argument’s existing axes. 
When you use the axis operator, it makes no dif- 
ference whether you use / or # to denote the re- 
duction operator. 


Domain of the derived reduce function: Any 
array whose elements would be acceptable as ar- 
guments of the dyadic function f. For example, 
+/ accepts as argument any array for which the 
successive pairs generated during summation are 
acceptable arguments of dyadic +. Note that 
whether a particular array is a valid argument 
may depend on the sequence of values along an 
axis, or the length of the axis. 


If the axis along which reduction takes place has 
length 1, the result is identical to the argument. 
(In principle, this is true even for an argument 
that would normally be outside the domain of the 
function; for example, A/2 or +/'A'. At present, 
SHARP APL does not accept reduction of a non- 
empty character array by a function defined only 
on numbers. ) 


If the axis along which reduction takes place has 
length 0, the argument is acceptable provided the 
function has an identity element; see the discussion 
of reduction of empty arrays. 


Result of the derived reduce function: An 
array having rank 1 less than the rank of the 
argument. However, the result produced by reduc- 
ing a scalar is a scalar. 


The result has the same shape as the argument, 
except that the axis along which reduction takes 
place is missing. 


Reduction considers the argument to be an array 
of vectors. For example, if the argument is a 3-by- 
4 matrix, you can think of that as 3 vectors, each 
of which has 4 elements. If the argument is a 
3-by-4-by-5 array, you can think of that as a 3-by- 
4 matrix of vectors, each of which has length 5. 
The result is obtained by calculating, for each of 
those vectors, the result you’d get by inserting the 
dyadic function f between each of its elements. 


For example, suppose Y is the following 3-by-7 
matrix: 


Y. 
T 2 3 4 5 6 7 
8 910 11 12 13 14 
15 16 17 18 19 20 21 


Then the expression +/Y considers Y as a set of 
3 vectors, each of which has length 7. The result, 
therefore, is a vector of 3 elements (one for each 
row of Y). 


The first element of the result is obtained by 
T+2+3+4+5+6+7 

The second element of the result is obtained by 
8 + 9 +10 +11 +12 +12 +14 

and the third by 


15 +16 +17 +18 +19 +20 +21 


For any array in which the axis of reduction is 
not empty and for which f\Y does not give a 
DOMAIN ERROR, the result of reduction is the same 
as the last position of the result of scan. That can 
be summarized by the following identity: 


f£/Y <> (14p¥)p((1tpy), 1) + f\Y 


Reduction along an axis of length one: As 
with scan, reduction along an axis of length 1 
returns values that are identical to those of the 


argument (but with the rank reduced by one, since 
the axis of reduction is eliminated in the result). 


Reduction along an axis of length zero: The 
result of reducing by function f along an axis of 
length zero, is the identity element for that func- 
tion. 


The identity element for a dyadic function is that 
value which, when used as one of the arguments, 
gives you a result that is equal to the other argu- 
ment, unchanged. For example, 0 is the identity 
element for addition since X+0 is always X, and 
1 is the identity element for multiplication since 
Xx1 is always X. 


For some functions, there’s an identity element in 
one argument but not in the other. For example, 
X+1 is always X, but that isn’t true for 1+X, nor 
for any other value of the left argument. Division 
is therefore said to have a right identity but no 
left identity. Residue has a left identity but no 
right identity, since 0|X is always X, but that isn’t 
true for X|0, nor for any other value of the right 
argument. 


Reduction by a function which has no identity 
element: There is no identity element for the 
following dyadic scalar functions: 


O ®© nx y 


For that reason, the system rejects reduction along 
an empty axis by any of those functions with the 
message DOMAIN ERROR. 


The following six functions have no identity ele- 
ment when applied to numbers in general, but do 
have an identity if considered solely with respect 
to the Boolean domain: 


< < = 2 >g 
The system therefore returns the Boolean identity 
for reduction by any of those functions along an 


empty axis, regardless of the type of internal stor- 
age used for the empty array. 
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Identity elements by function 
for reduction along an empty axis 







Function Value 


+ Plus 0 Both 
Times 1 Both 


Identity 











- Minus 0 Right 
+ Divide 1 Right 


x Power 1 Right 
Logarithm None 









f Maximum 
L Minimum 


-Infinity Both 
+Infinity Both 













| Residue 0 Left 
! Combinations 1 Left 
Circular 


And 
Or 


Nand 
Nor 


= Equal 1 Both 
Not equal 0 Both 






< Less 0 Left 
Not greater 1 Left 











2 Not less 1 Right 
> Greater 0 Right 









Note: For the values plus and minus in- 
finity, the system returns the largest and 
smallest numbers that are within its powers 
to represent, about 7.237005577E75 and 
~7.237005577E75, respectively. 


Reductions of non-associative functions: The 
f reduction of a vector is computed by inserting the 
dyadic function f between each of the consecutive 
members of a vector. Because of the general rule 
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that any function takes as its argument the entire 
expression to the right of it, any expression such 
as 


AfBfcfD 
is equivalent to 
Af (Bf (Cf D)) 


When f is an associative function, the order of 
execution within the reduction of a vector is, in 
principle, immaterial. But for a non-associative 
function, the order of execution matters. The sys- 
tem always observes the general rules of APL syn- 
tax while computing a reduction by any non-asso- 
ciative function. That is, the argument of each 
function is the entire expression to its right, and 
so functions are evaluated from right to left. 


Alternating functions: For the non-associative 
functions minus and divide, reduction produces the 
so-called alternating functions. 


For a vector Y, -/Y is equivalent to the sum of 
the elements at odd positions in Y, minus the sum 
of elements at even positions. That is called the 
“alternating sum.” 


For a vector Y, +/Y is equivalent to the product 
of the elements at odd positions in Y, divided by 
the product of elements at even positions. That is 
called the “alternating product.” 


Other effects of order of execution: Effects 
produced by order of execution were discussed in 
the section on scans. An effect of order of execu- 
tion may be evident in reductions by + - x or + 
if some of the intermediate results exceed the sys- 
tem’s ability to represent them precisely. The sys- 
tem executes reductions of associative functions 
from left to right rather than right to left. The 
possible effect of this shortcut on calculations in- 
volving + or x is discussed in more detail in the 


section on scans. 


Chapter 20: 


DYADIC 
OPERATORS 





eer 


f[7] Y Axis 


Left argument: Any of the functions illustrated 
in the following paradigms (in which the right 
argument of the axis operator is shown as J and 
the right argument of the derived function is 
shown as Y): 


X,{I] Y  Catenate (or laminate) 
[I] Y Reverse 
XLI] Y Rotate 
X/[I] Y Compress 
X\[I] Y Expand 
f\CI] Y Any of the derived scan functions 
f/[I] Y Any of the derived reduction functions 


Right argument: A 1-element array (either a 
scalar or a 1-element vector), indicating one axis 
of the argument of the derived function. Axis- 
numbers are subject to the index origin DIO. 


For all of the functions except laminate, the value 
of the right argument J must be an integer indicat- 
ing one of the existing axes of the array that is 
the right argument of the derived function. 


The dyadic function denoted by the comma is 
sometimes called ‘“‘catenate” and sometimes “lami- 
nate,” depending on whether or not the result has 
a rank greater than the rank of either argument. 
When both X and Y are scalars, or when , is 
used with a fractional argument to the axis opera- 
tor, the function is laminate. Otherwise, it’s cate- 
nate. When J is a fraction, its value must differ 
by an amount less than 1 from the axis number 
of one of the existing axes in the arguments of 
laminate. 
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Result: A derived function. The derived function 
is the same as the function that appears as the left 
argument, except that the axis along which it ap- 
plies is the axis indicated by the right argument. 


The effect of the axis operator on each of the 
functions with which it can be used is described 
in the section devoted to that function. 


f.g Product 


Syntactically, the product operator, denoted by the 
dot symbol, must always be used dyadically. That 
is, it can’t appear without a left argument. How- 
ever, the left argument may be either a dyadic 
scalar function, or the symbol o (“null”). This 
has the effect of creating what amounts to a mo- 
nadic use of the product operator; it is at present 
the only use of the null symbol in SHARP APL. 


A derived function produced by monadic use of the 
product operator is called an outer product, while 
a derived function produced by dyadic use of the 
product operator is called an inner product. In 
what follows, they are discussed separately. 


o.g The g outer product 


Left argument: The symbol © “null” indicat- 
ing that no left argument is supplied. 


Right argument: 
function. 


Any dyadic scalar primitive 


Result: A derived function identical to the argu- 
ment function g, except that its conformability 
rules are different. 


The derived function Xo .gY differs from the scalar 
function XgY in the following way. For XgY, the 
arguments X and Y must conform in rank and 
shape, and the resulj has the same shape as X or 
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3 


y. An element of the result is computed by 
evaluating the function g for the corresponding 
element of X paired with the corresponding ele- 
ment of Y. 


By contrast, the outer product Xo.gY has no re- 
quirement that the arguments X and Y conform in 
rank or shape. Instead, each element of X is paired 
successively with each of the elements of Y, until 
the function g has been evaluated for every possi- 
ble pairing of an element of X with an element of 
Y. The outer product thus evaluates the function 
for the Cartesian product of the values in the two 
arguments. 


Domain of the derived outer product function 
Any pair of arrays, regardless of rank or shape, 
such that each element of the left argument X 
paired with any member of Y is an acceptable 
argument-pair for the function g. 


Result of the derived outer product function: 
An array whose shape is the shape of the left 
argument, followed by the shape of the right argu- 
ment. That is, for the result R of Xo .gY: 


pR <> (pX),pY 


The result is obtained by pairing each element of 
X with each element of Y. One might specify the 
result R by the following formula: 


SHAPE + (pA),pB 
R + (Q(OSHAPE)pQX) g SHAPEpY 


Notice that when one of the arguments is a scalar, 
using an outer product gives you the same result 
as you’d get using the function without the product 
operator. 


ann 


Illustrative uses of outer products: The outer 
product forms an exhaustive table of pairings of 
each element from the left argument with an ele- 
ment from the right argument. When the argu- 
ments are vectors, this forms a familiar function 
table. For example, if X is the first three integers 
and Y the first five, then Xo .xY forms a multipli- 
cation table. You could label such a table as fol- 
lows: the elements of the left argument label the 
rows, while the elements of the right argument 
label the columns. The multiplication table for X 
and Y might then appear like this: 


1 2 30.x12345 





[1] 2[3]>.x[1[2[3[4[5] 




















result 





Of course, the labelling in the foregoing illustra- 
tion is afterwards; the result of the outer product 


is simply the array of values that appear as the 
body of the table. 


Below appears a division table formed from the 
same vectors X and Y: 


1 0.5 0.3333333333 
2 1 0.6666666667 
3 1.5 1 


0.25 
0.5 
0.75 


The expression Xo.2Y produces a logical map 
showing where an element of X is not less than 
an element of Y: 


BRR 
ereo 
eoo 
ooo 
ooo 


Similarly, Xo. |Y produces a table of residues or 
remainders: 


00000 
roO 1 g-i 
12012 


And Xo.-Y gives you a table of the differences 
between elements of X and those of Y: 


0 1 2 73 Cy 
101 “2 “3 
2 A es T2 


Since in APL the circular function is also a scalar 
dyadic function (in which the left argument deter- 
mines which of the various circular functions is to 
be evaluated), the expression Xo.OY produces a 
3-by-5 table in which the top row contains sines, 
the second row cosines, and the third row tangents: 


ooo 
OFN 
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0.8414709848 _0.9092974268 0.1411200081 0.7568024953 ~Q.9589242747 
0.5403023059 0.4161468365 0.9899924966 0.6536436209 0.2836621855 © 


1.557407725 ~2.185039863  0.1425465431 


If ALF is a 26-element vector containing the letters 
of the alphabet, and TEXT is a vector representing 
the text of a document, then ALFo.=TEXT gives 
you an incidence map showing where the letters 
of the alphabet are found in the text, while 
+/ALFo.=TEXT gives you the number of occur- 
rences in TEXT of each letter in ALF. 


f.g Inner product 


Left argument: Any dyadic scalar primitive 
function. 


Right argument: Any dyadic scalar primitive 
function. 


Result: A derived function. The derived function 
is dyadic. It is referred to by the names of the two 
functions that are the arguments of dot, followed 
by “inner product.” For example, ^.= is called the 
“and-dot-equals inner product,” while +.x is cal- 
led the “plus-dot-times inner product,” and so on. 


Arguments of the derived inner product func- 
tion: Each of the inner product functions takes 
two arguments. Each argument is considered as a 
collection of vectors. That is, one axis (the last or 
the first) is devoted to some sort of vector repre- 
sentation. Each of those vectors is considered as a 
unit, and the result contains an element for each 
vector. 


The inner product functions require that the axis 
devoted to a vector representation be the last axis 
of the left argument and the first axis of the right 
argument. For that reason, the arguments must 
conform in length along those axes. There may be 
any number of other axes, each of any length. 


Notice that if, under each argument of an inner 
product, you write its shape vector, the adjacent 
elements of the two shapes are the ones that must 
match. To illustrate, suppose X has shape 
3 12 7 and Y has shape 7 40, it is the adjacent 
7s that must match: 
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4.157821282  3.380515006 





Extending one argument to match the other: In 
general, the inner axes (that is, the last axis of 
X and the first axis of Y) must match in length. 
However, the system also accepts two other cases. 


When the inner axis of one argument has length 
1, but the inner axis of the other argument has 
some other length, the system treats the length-4 
axis as though it were extended to match the 
length of the other one, replicating in each position 
whatever value is in the one position. 


When one argument is a scalar, the system treats 
it as if it were a vector of the same length as the 
inner axis of the other argument, replicating at 
each element the value of the scalar. 


Neither of these extensions affects the shape of the 
result. 


Orientation of the arguments of inner products: 
Because each inner product function considers the 
vector representation to be in the last axis of one 
argument but the first axis of the other, if you 
have, an application whose arguments are in the 
same form, you'll probably have to transpose one 
of them when you use it as the argument of an 
inner product. For example, suppose you have two 
tables of names, a master table called MASTER and 
a sample table called SAMPLE. Each consists of a 
matrix having a fixed number of columns and any 
number of rows. Thus, the representation (a 
name) is arranged along the last axis (columns). 
To prepare a map showing where the sample ma- 
trix matches the master matrix requires transpos- 
ing one of them; for example: 


MASTER ^.= SAMPLE 


Which axis is “representation” may well be arbi- 
trary, or depend on your purpose in interpreting 
the data. For example, suppose X is a score matrix, 
containing the scores of a group of people on each 
of a series of tests. The matrix is arranged so that 
the first axis differentiates people, and the last axis 
differentiates tests. You might consider this a col- 
lection of people, each represented by a vector of 
test scores, or a collection of tests each represented 
by the scores of a sample of people. If what you 
want are the intercorrelations of the tests, that 
amounts to representing each test by the set of 
scores your sample people got. Interpreting the 
data that way, it’s the first axis that contains the 
representations. The cross product (summing over 
people for each possible combination of tests) is 
a part of the procedure to calculate correlation 
coefficients. It could be obtained by 


(QX) +.x X 


Result of the inner product functions: The 
inner product works in the same way as the outer 
product, except that the outer product is con- 
cerned with scalars, while the inner product is 
concerned with vectors. 


The outer product pairs each scalar element from 
the left argument in turn with each scalar element 
of the right argument. By contrast, the inner 
product pairs each vector along the last axis of 
X in turn with each vector along the first axis of 
X. 


For each pairing of a vector from X with a vector 
from Y, there is a scalar element in the result. If 
a vector from X is called VX and a vector from Y 
is called VY, an element of the result is computed 
as 


f/ VX g VY 


That is, the system evaluates the dyadic function 
g for the corresponding elements of the two vec- 
tors, and then applies to those results the monadic 
derived function f/. 


Shape of the result of an inner product: The 
result produced by an inner product resembles the 
shape produced by outer product, except that the 





two inner axes (the ones interpreted as a vector 
representation) disappear in the result. Hence, the 
shape of the result R you get by applying the f.g 
inner product to argument X and Y is given by: 


oXf.gY <> ( 14pX),1+pY 


An example using matrices: Suppose X has 
shape 3-by-4, while Y has shape 4-by-5. In 
evaluating the inner product Xf.gY, the system 
treats the right argument Y as a collection of col- 
umn-vectors. That is, each vector lies in a particu- 
lar column. Stating it the other way, each vector 
has a fixed column location, but is ranged over all 
the rows. (That’s what is meant by saying that 
the vector is arranged across rows.) 


The system treats the left argument X as a collec- 
tion of row vectors. That is, each vector has a fixed 
row location, and is arranged across columns. 
























































result 
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The result is a matrix that has three rows (one 
for each of the three row-vectors in X) and five 
columns (one for each of the five column-vectors 
in Y). The diagram shows how a given element 
of the result is computed by computing 


RLROW;COL] <+ £/ X[ROW;] g YC;COL] 


for the case in which f is plus and g is times. 


Relation between inner and outer product: 
You could compute the inner product in terms of 
the outer product by the following formula: 


AXTS+(1ppX)-QIO=0 
DIAG<(1ppX), (ippY)+AXIS-QIO 
Rf/(AXIS] DIAG&Xo .gY 


Inner product and matrix product: When X 
and Y are matrices, the inner product X+ . xY is the 
same as the ordinary matrix product of matrix 
algebra. 


Note that matrix product has an inverse function, 
since, where X and Y are square matrices, 
Y <> (X+.x¥)@X 


See the discussion of matrix division and matrix 
inverse. 


Illustrative applications of inner product: 
There are 21 dyadic scalar primitives, any of 
which can, in principle, appear as either argument 
of the product operator. That makes 441 conceiv- 
able inner product functions. Of course many of 
these combinations are of little interest. The fol- 
lowing illustrate a few of the more common appli- 
cations. 


Evaluation of polynomials: The ordinary ma- 
trix product +.x may be used to evaluate polyno- 


mials in X. Suppose COEFF is a table (again, of’ 


any rank or shape) containing the coefficients of 
the various polynomials to be evaluated. The first 
axis of COEFF contains the various terms, starting 
with the constant term, the first degree, second 
degree, and so on, up to whatever degree is de- 
sired. Let POWERS be an array in which each 
member of X is raised to each of the powers, from 
zero up to whatever degree is implied by the 
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~n~ 


length of the first axis of COEFF. That can be 
calculated by: 


COEFF+Xo .*(11tpCOEFF) -QI0 


Then all of the polynomials for each of the sets 
of coefficients in COEFF can be calculated by: 


POWERS+ .xCOEFF 


Product of powers: An integer may be repre- 
sented by its prime factorization. That is a vector 
indicating to what power each of the possible 
primes must be raised. The number itself is then 
the product over each of those powers. For all the 
primes in order out to the largest one needed, 
suppose FACTORS is an array containing the 
power to which each must be raised. Then the 
values represented by such a set of prime factors 
are found by 


PRIMESx .*F ACTORS 


where PRIMES is a vector of the values of as many 
primes as are needed to match the length of the 
first axis of FACTORS. 


Locating character strings from one table with- 
in another table: Inner products constructed 
from logical functions on character data are fre- 
quently useful in handling textual data. Suppose 
SAMPLE is a character matrix in which each row 
contains characters that spell a word, phrase, or 
name. Suppose REFERENCE is a similar table of 
recognized words or phrases. You need to know 
where within REFERENCE each row of SAMPLE is 
to be found. As has been mentioned, a map show- 
ing where each row of SAMPLE is entirely equal 
to a row of REFERENCE is obtained by 


REFERENCEA .=QSAMPLE 


Alternatively, rather than identifying those rows 
of REFERENCE which are entirely equal, you might 
wish to eliminate those that are in any way differ- 
ent, by an expression such as 


REFERENCEV .#XSAMPLE 
If you would like to convert the resulting Boolean 


map so as to identify the number of the row on 
which each match was found, that in turn might 


involve another inner product. Suppose TOTA is a 
vector of consecutive integers, with as many mem- 
bers as there are rows in REFERENCE. The loca- 
tion of the match for each row of SAMPLE is found 
by: 


IOTA+ .xREFERENCEA .=SAMPLE 


The preceding formula assumes that REFERENCE 
does not contain duplicate entries. But if it did, 
and you wanted the highest entry, you could find 
it as 


IOTAT .xREFERENCEA .= SAMPLE 


If you’re interested in the extent of agreement 
(rather than simply the Boolean decision whether 
or not there is perfect agreement), you might get 
that by 


REFERENCE+ .=QSAMPLE 


Permutation and partition matrices: You can 
permute or partition the members of one array by 
making one of the arguments of an inner product 
a Boolean array. The Boolean matrix B might 
contain a column for each of the desired partitions. 
In the expression B+.xY, a 1 in B serves to indi- 
cate that a row of Y is included in a partition, and 
a O that it is not. 


When there are as many partitions as there are 
rows, and each partition contains exactly one 1, 
the matrix is a permutation matrix. It specifies 
an order in which the rows of Y are represented 
in the result of B+.xY. 


A Boolean array acts as a partitioning device when 
the function g, applied to 0 in the Boolean array 
and any value in the other array, yields the identi- 
ty element for function f. For example, with the 
+.x inner product, Ox any value in the other array 
yields 0, which is the identity element for +. That 
is, elements marked 0 in the Boolean array have 
no effect on the sums. 


Similarly, in an inner product such as Xx.*B, 
raising an element of X to the power 0 yields 1, 
which is the identity element for x. 


Analysis of connectivity: You can evaluate the 
connectivity of a matrix with inner products. If 
each row of a matrix C indicates a node of a 
network, and each column a connection to that 
node, then the existence of a direct connection is 


found by 
CV. ARC 

and the number of connections by 
C+. ARC 


Applications in circuit analysis will be familiar to 
electrical engineers, but analogous calculations 
occur in other fields. For instance, the connectivity 
of an urban transit system might be documented 
by tabling the stops as rows of a matrix, and the 
lines that serve them by columns. If such an array 
is called MAP, the connectivity of the system is 
found by 


C+(QMAP)v . AMAP 


The result C is a square matrix showing where 
one line intersects another. A map showing which 
line is connected to another is found by 


CV. AC 


and showing which line can be reached in a two- 
step journey by 


CV .A®CV. AXC and so on. 


Inner product using reduction by a non-asso- 
ciative function: The left argument f of the 
product operator serves to reduce each of the vec- 
tors generated with the right argument function g. 
The alternating sum or product may serve there 
as it does in reductions. For example, the Mac- 
laurin series for approximation of the sine is 
shown conventionally as the alternating sum of 
ratios of successive odd powers: 
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x? x5 x7 ax? 


sinx © x -s tK O7 +i 
In APL, this simplifies to the -.+ inner product, 
as follows: 

ODD- 1+2xik 


SIN X <> (Xe.*ODD)-.+!0DD 


icy 
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Chapter 21: There are three system functions devoted to the 
management of batch APL tasks: ORUN, ORUNS, 
and BOUNCE. The function [RUN permits you to 
SYSTEM FU NCTIONS start an N-task. To start a B-task, you use the 
defined function BYASKREQ in workspace 
1 BTASK; its syntax is very like that of ỌRUN. 
FOR Immediate and delayed batch tasks (N-tasks, and 
B-tasks) are described in the publication “Batch 

Tasks in SHARP APL.” 


BATCH TASKS 


The function [RUNS permits you to monitor the 
current status of any task that’s currently running 
on your account or at your request, including T- 
tasks, N-tasks, and B-tasks. 


ReRUN Y Run task Y 


Argument: A character vector describing one N- 
task you wish to start. 


The system considers the vector Y to consist of five 
free-form fields separated by blanks. The fields are 
as follows: 


1. Sign-on ID: The account number and sign- 
on password of the user on whose account the task 
is to be run (the “owner” of the task). You sepa- 
rate the account number from the password with 
a colon. If the N-task is to run under your own 
account, you can elide the account number and 
password, and put only the colon. 


2. Load-WS: The workspace that you want the 
system to load in order to start work on the task. 
If the workspace is stored in a library other than 
the library that belongs to the account identified 
in the first field, the library number must be in- 
cluded before the name of the workspace. If the 
workspace is locked, to the right of the workspace 
name you must include a colon and the workspace 
password. 
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Where the N-task is to be split from your current 
active workspace, use only a colon in place of any 
other workspace identification. 


3. Save-WS: A name under which the active 
workspace of the N-task can be saved when work 
is halted. The name is understood to be the name 
of a workspace in the library of the account which 
owns the task (i.e. the account identified in the 
first field). If you want the saved workspace to be 
locked, follow the workspace name with a colon 
and password. 


You may not elide this field. That is, you must 
specify a workspace name under which the active 
workspace can be saved. The name must be a valid 
workspace name, and the account that is to own 
the N-task must have a workspace quota big 
enough to permit saving it. 


The N-task’s active workspace is not saved if work 
is halted by a clear workspace. A clear workspace 
can be produced by trapping event 2001 (see 
“System Function and Variables for Event Trap- 
ping”) or by using the function CLEAROUT from 
workspace 1 WSFNS). A clear workspace produced 
inadvertently as an effect of certain system errors 
is saved, and contains DER indicating event 67 or 
68. 





4. CPU limit: The maximum number of CPU 
units that may be used during running of the N- 
task. If 0, the N-task may run without limit. This 
field may not be elided. 


5. Connect limit: The maximum number of 
elapsed seconds that the N-task may run. If 0, the 
task may run without limit. This field may not be 
elided. 


Effect: The system creates a new task and starts 
executing it. The new task is an N-task; that is, 
a task that is not associated with a terminal. 


If your instructions in the argument of [ỌRUN in- 
struct the system to start the N-task by loading a 
workspace (that is, if you use the second field to 
identify a workspace), the system loads that work- 
space, and then executes the latent expression 
OLX. But if the task was started by splitting your 
active workspace, execution continues with what- 
ever was being executed in your active workspace. 


197 SYSTEM FUNCTIONS FOR BATCH TASKS 





Whichever way you start an N-task, at its start, 
the visible values of the session variables QHT and 
OSP are the same as the visible values that those 
variables had in the parent task’s active workspace 
when you invoked QRUN. 


Once started, execution of the N-task continues 
until halted. Execution may be halted by a normal 
end, or by any error, or by external events such 
as [BOUNCE or a system crash. Any request for 
terminal input to an N-task is considered an error. 
Any request for output to a terminal is ignored; 
however, if DOUT has first been executed appropri- 
ately, output that would otherwise go to the termi- 
nal may usually be directed instead to a file. 


When work is halted for any reason, the active 
workspace is saved under the name indicated in 
the third field of the argument of (RUN. However, 
if the active workspace has been cleared by 
CLEAROUT or a (TRAP containing the trap defini- 
tion 2001 D CLEAR, the system doesn’t save it. 


Watch out: If the name you give here is the 
name of a workspace that already exists, when 
your N-task is halted, the workspace that the sys- 
tem then saves will replace the workspace you’d 
saved earlier. 


Result: A 2-element numeric vector indicating 
either that the N-task was successfully started or 
a reason why it was not. The possible values are 
as follows: 


Result Meaning 


Result received in the active work- 
space of a split-workspace N-task 


Task n successfully started 


Argument found to be invalid at char- 
acter n 


System capacity for N-tasks exhaust- 
ed 


You already have the maximum num- 
ber of N-tasks running (currently 4) 











The proposed N-task owner does not 
have workspace quota big enough to 
permit saving a workspace when the 
task is halted 








When the system loads the workspace 
you asked for, it encounters a 
WS FULL condition because there isn’t 
room to copy in the session variables 
from your active workspace 








When loaded, the workspace you 
asked for has a symbol table full con- 
dition (because it did not contain 
symbols for its system variables nor 
space in its symbol table to insert 
them) 







Sign-on number not in system, or 
password invalid 






Sign-on number locked out 






The workspace you asked for cannot 
be found 







The workspace you asked for contains 
an invalid (LX 






System capacity for tasks exhausted 






User not permitted to use QRUN 









The workspace you asked for cannot 
be read (as the result of some sort of 
hardware error) 






R<QRUNS Runs: Your active tasks 


This function reports the current status of all tasks 
that are now running and which either you initi- 
ated or you own. It is a niladic function. 


Result: A numeric matrix, having eight columns, 
and one row for each task. The top row always 
refers to the task which invoked DRUNS. The col- 
umns have the following meanings: 


SYSTEM FUNCTIONS FOR BATCH TASKS 


on 


1. Task number 


2. Account number of the owner (i.e. person on 
whose account the task is being run) 


3. Account number of the initiator of this task 
4. Type of task, according to the following code: 


o T-task 
1 N-task 
2 B-task 


5. CPU units consumed since start of the task 
6. Elapsed seconds since start of the task 


7. Task’s CPU limit in seconds (always 0 for a 
T-task ) 


8. Task’s connect limit in seconds (always 0 for 
a T-task) 


R4 J]BOUNCE Y Bounce the tasks numbered Y 


Argument: A vector of task numbers. 

Effect: The tasks identified in Y are “bounced.” 
That is, for each of them, execution is halted, the 
active workspace is saved, and the task is signed 
off. 


You can bounce a task if it is one that you own 
(that is, one running under your account number) 
or if it is one that you started, but only while it 
is currently active. 


Notice that an N-task can bounce a T-task, so that 
it’s possible from your terminal to start an N-task 
which then bounces you from the terminal you are 
using. 


You can bounce a B-task running under your ac- 
count number. However, when you do, you must 
refer to it by its current task number. You can 
find out the task number under which your re- 
quest is running by using the function INQ in 
workspace 1 BIASKREQ. Note that a B-task gets 
a new task number each time it is restarted. 
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Following (BOUNCE, the active workspace of the 
bounced task is saved under the name indicated in 
the save-WS field of the QRUN statement that start- 
ed it. The active workspace of a T-task is saved 
under the name CONTINUE. 


Result: A Boolean array having the same rank 
and shape as the argument Y, containing 1 for 
each task successfully bounced, and 0 otherwise. 
An element of the result may be 0 if the corre- 
sponding element of the argument Y is not now 
signed on, is not a valid task number, or is not 


within your authority to bounce. 
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Chapter 22: 


SYSTEM 
FUNCTIONS 
FOR 
REPRESENTING 
AND 


CONVERTING 
DATA 





The functions DFI and OVI allow you to convert 
character data to numbers. The function DFMT is 
used to convert numeric data to characters; the 
capabilities of [FMT in some respects overlap those 
of the monadic and dyadic use of +, described in 
the chapter on non-scalar primitive functions. 


RFI Y Form numeric input from 
character vector Y 
RWI Y Validate numeric input from 


character vector Y 


Argument: A character vector. A character sca- 
lar is treated as if it were a 1-element vector. 


The argument Y is considered to be made up of 
fields. A field is a sequence of non-blank charac- 
ters. Each field is separated from the next by at 
least one blank (and possibly by many blanks). 
Fields don’t have to have the same length. 


Result of [FI Y: A numeric vector. The num- 
ber of elements in the result is the number of fields 
in the argument. 


For each field of Y whose characters form a valid 
representation of a number, the corresponding ele- 
ment of the result is that number. Where the char- 
acter representation shows more digits than the 
system can deal with (i.e. more than about 16 
significant digits), the corresponding element of 
the result is approximated. Where the character 
representation in a field shows a number that ex- 
ceeds the system’s maximum representable magni- 
tude, the corresponding element of the result con- 
tains the number having the greatest magnitude 
that the system can represent (that is, about 
7.237E75). 
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For each field that does not contain a valid charac- 
ter representation of a number, the corresponding 
element of the result is zero. A valid representation 
is one written in any of the forms that would be 
acceptable as numeric constants when you're en- 
tering data from the keyboard. In particular, to be 
valid, a representation must mark negative values 
by the negative symbol ~ as its first significant 
character. It may not contain embedded within it 
any spaces, commas, slashes, or indeed any charac- 
ters other than the digits 0123456789, the deci- 
mal point, the negative sign, and the Æ used to 
indicate exponential notation. Thus, the following 
character vector V1 contains four fields, each of 
which is valid: 


V1<'18.6 00017. .3 1E 9! 


while the following character vector V2 contains 
five fields, none of which is valid: 


V2<'9/12/78 $6,000,000 -7 F9 SEPT78' 


Result of OVI Y: A Boolean vector. The number 
of elements in the result is the number of fields 
in the argument. 


For each field of the argument that contains a 
valid character-representation of a number, the 
corresponding element of the result is 1. All other 
elements of the result are 0. 


For example, if you applied DVZ to the examples 
V1 and V2 used previously, you’d get 


DVI V1 
11141 


OVI V2 
00000 


You could use DVZ to disregard fields of character 
input that do not contain valid representations of 
numbers. Suppose Y is a vector obtained from the 
keyboard. Then 


(DVI Y)/OFI Y 


returns the numeric value of each of the valid 
fields in Y, and nothing else. But notice that this 
causes a field such as 6,000,000 or 3/4 to be 
disregarded completely. 


The expression p[VJ Y gives you the number of 
fields in a character vector. 


R-X OFMT Y The X format of Y 
R-X DFMT (Y1;Y2;Y3)The X format of the list 
Vig Ys Y3 


The system function DFMT generates a character 
matrix containing representations of the one or 
more arrays that are its right argument, according 
to formatting rules provided in its left argument. 


Right argument: The right argument may ei- 
ther be a single array, or a list of expressions each 
of which gives rise to an array. If the argument 
is a list of expressions, you separate the various 
expressions by semicolons, and the entire list is 
enclosed in parentheses. See the section entitled “A 
Note About Semicolons and Lists.” 


Each array resulting from the various expressions 
in the list (or the single array, when the argument 
is not a list) must have rank 2 or less. A vector 
is treated as if it were a one-column matrix. A 
scalar is treated as if it were a 1-by-1 matrix. It 
is not necessary that these matrices have the same 
number of rows. 


The data provided in the right argument are for- 
matted column by column; the left argument X 
contains one or more formatting phrases. Each 
phrase from the left argument is used in turn to 
govern the appearance of one of the columns of 
data from the right argument. In general, each 
array on the right must be numeric, except when 
the corresponding format phrase in the left argu- 
ment calls for character data, in which case it must 
be character. 


Left argument: A character vector. 


The left argument X is considered to be divided 

into phrases. A phrase is a sequence of characters 

describing how one field of the result—that is, one 

block of consecutive print positions—is to be pre- 

pared to represent one column of the right argu- 

ment. Within the left argument X, the comma 
, serves to separate formatting phrases. 
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Repetition factor: Where several consecutive 
fields of the result are to be formatted in the same 
way, a phrase in X may begin with a number. The 
number is a repetition factor. Suppose that AAAA 
and BBB and CCCCCC are three format phrases. 
Then the following are equivalent ways of saying 
the same thing, without a repetition factor, and 
then with one: 


'AAAA, BBB, CCCCC, CCCCC! 
'AAAA, BBB, 2CCCCC' 


A single repetition factor may be applied to several 
fields by enclosing them in parentheses. The fol- 
lowing are equivalent: 


'CCCCC, AAAA, BBB, AAAA, BBB, AAAA! 


'CCCCC, 2(AAAA, BBB), AAAA' 


Formatting phrases may be nested within paren- 
theses up to four levels of parentheses. 


Text delimiters: Within a format phrase, you 
may want certain characters to be reproduced in 
the result. Such characters have to be enclosed in 
text delimiters. Text delimiters serve the same 
purpose as quote marks: they set apart characters 
that are to be taken literally rather than inter- 
preted. Within a formatting phrase, you may use 
any of five different pairs of text delimiters. These 
text delimiters do not include the quote mark 

' generally used as a text delimiter in APL. A 
literal text runs from the leftmost instance of one 
of these pairs of characters to the next occurrence 
of the matching character that ends the text: 


Tonia D 
Erse ii 
Moses N 


Key letter within each format phrase: Within 
each phrase, one letter indicates the type of format 
you want. In addition, there is one type of phrase 
which has no key letter, but consists entirely of a 
string of text enclosed in text delimiters. 


Qualifiers and decorators: Within each phrase, 
to the left of the key letter, under some circum- 
stances you may insert qualifiers or decorators. A 
list of these appears following the list of types of 





format phrases. If you’re allowed to use one or 
more qualifiers or decorators with a particular 
type of phrase, that’s indicated by a letter q ahead 
of the key letter. 


Types of formatting phrase: The possible types 
of phrase are listed in the table. 


For w, substitute a number showing the 
total width—that is, the number of print 
positions—you want the resulting field to 
take up. 


For d, substitute a number showing the 
number of digits. That will be under- 
stood as the number of decimal digits in 
a decimal format, or the number of sig- 
nificant digits in an exponential format. 


For m, substitute the number of repeti- 
tions you want—that is, the number of 
consecutive fields you want this format 
to be used for. If you only want one, you 
can leave this out. 


mq Iw Integer 


Fw.d Fixed point fraction 


Ew.d Exponential fraction 
Aw Character 
G <text> Picture 


Xn Relative reposition by 
n 


Tn Absolute reposition to 
n 


<text> Text insertion 


List of qualifiers and decorators: Within a 
phrase, to the left of the key letter you may insert 
one or more qualifiers or decorators. Some of ‘these 
may be used only with certain key letters. Where 
you use several within the same phrase, their order 
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doesn’t matter. Qualifiers supply general rules 
governing the way the field appears; decorators 
supply specific text to be used within the field 
under certain conditions. 


R<text> Background: print text in 
available positions not occu- 
pied by digits and not occu- 


pied by text supplied by 


Qualifiers 


B 


Where the value is zero, leave the 
field blank. 


Insert commas between triplets of 
digits to the left of the decimal 
point. Not available with G format. 


Scale factor. Before formatting, 
multiply the data by the power of 
10 indicated by n. 


Left-justify. Not available with G 
format. 


Print leading zeros. Not available 
with G format. 


Decorators 
eel 


M<text> 


P<text> 


Q<text> 


Print text to the left of left- 
most digit of a negative 
number (instead of `). 


Print text to the right of 
rightmost digit of a negative 
number. 


Print text to the left of a 
non-negative number. 


Print text to the right of the 
rightmost digit of a non- 
negative number. 





other qualifiers. 
S<text> Substitute symbols. Consid- 
ering text as a sequence of 
pairs, where the first mem- 
ber of the pair would ordi- 
narily be used, substitute the 
second. Permits substitution 
of decimal point, comma, 
overflow symbol, leading 
zero, exponent symbol, or 
blank in formats I F BE, 
and codes Z and 9 in format 
G. 





Result: A character matrix. The number of rows 
in the result is the same as the number of rows 
in the argument, or, when the right argument is 
a list, as the number of rows in the array having 
the greatest number of rows. 


The total number of fields in the result is the same 
as the number of columns in the right argument, 
plus any intervening fields for which no data col- 
umn is required. The total number of columns in 
the result is the sum of the widths of the various 
fields actually used. 


Where the number of fields specified in the left 
argument differs from the number of columns in 
the right argument, phrases are used, or reused 
cyclically, until all columns of the right argument 
have been formatted. 


When a numeric value can’t be represented in the 
number of digits that the controlling phrase re- 
quests, the field is filled with the overflow charac- 
ter. That also happens when the data are numeric 
but the controlling phrase expects characters, or 
when the data are characters but the controlling 
phrase expects numbers. 


Note: The formatting functions [FMT and 7 are 
described in greater detail in the publication “Re- 


port Formatting in SHARP APL.” 


203 SYSTEM FUNCTIONS FOR REPRESENTING AND CONVERTING DATA 


Chapter 23: 


SYSTEM 
FUNCTIONS 
FOR 
FUNCTION 
DEFINITION 





There are two main ways you can edit a function: 


1. Using the V function editor (described in the 
chapter on modes of interaction at a terminal). 


The V function editor is restricted to work with 
global functions. It can be used only from the 
keyboard of a T-task. (In that respect it resembles 
a system command.) It is the only mechanism that 
lets you revise the definition of a suspended func- 
tion and then resume its execution. 


2. Using the system functions for function editing, 


OCR, OFX, OFX, and DFD. 


These system functions always affect the visible 
meaning of a name (see the discussion of local and 
global uses of names). They’re the only mecha- 
nism you can use to create or edit a local function. 
When a local function is suspended (because of 
an error or interruption), although you can use 
DFD or (ICR to display its definition, you can revise 
that definition only by a process that involves eras- 
ing the current definition and replacing it with a 
new one. You don’t have a way of revising a local 
definition and resuming its execution. 


This chapter describes the use of OCR, DFX, 
DEX, and DFD. 


Two groups of system functions: The capabili- 
ties of QFD overlap those of OCR, OFX and DEX. 
The reason is historical. The function [FD (mne- 
monic for “function definition”) is descended from 
a facility which was introduced when there 
weren't any other functions for editing functions. 
IBM subsequently introduced the other three 
functions. SHARP APL now includes both. The 
capabilities of QFD on the one hand and of the 
three functions (CR, OFX, and DEX, are almost 
identical. They differ slightly in the forms in 
which you’re allowed to supply their arguments 
and in the way they return their results. 
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The function OFD is dyadic, whereas the other 
three are monadic. The left argument of OFD is 
a number which indicates which function you 
mean. For instance, 3 [FD Y has the same effect 
as DFX Y. The four possible values of the left 
argument of DFD, and the other functions to which 
they correspond, are summarized in the table: 


If the function’s definition includes within it a 
carriage return as a character constant, that ap- 
pears in the result as a carriage return followed 
by six blanks. That way, the next character fol- 
lowing the carriage return constant appears in- 
dented, in the same way as the rest of the defini- 
tion. 


Comparable forms of system functions for function editing 
D 


1 DFD Y (none) 


Represent function Y as a vector with embedded carriage 


returns, including line numbers and leading and trailing 


Vs 


2 DED Y Represent function Y as a matrix, without line numbers 


or Vs 


3 DFD Y OFX Y 


Fix a function based on the definition contained in the 


character array Y (see text for discussion of differences) 


6 DFD Y DEX Y 


Expunge the visible meaning of the names contained in 


character array Y 


7 OFD Y (none) 


Lock the definitions of the visible functions named in Y 


(4 DFD and 5 DFD have no use in SHARP APL.) 


Rei DFD Y Vector representation of 
function named in Y 


Argument: A character vector (or scalar) con- 
taining the name of a visible function. 


Result: A character vector containing the defini- 
tion of the function named in Y. When displayed, 
the result of 1 OFD 'FN' is identical in appear- 
ance to the display produced by the del editor in 
response to VFENCOJV. 


The result shows four blanks and the character 
V at the beginning. Each line after the header is 
labelled with line numbers enclosed in brackets. 
The start of a new line is indicated by a carriage- 
return character embedded in the result. At the 
end of the definition, there is a carriage return, 
four blanks, and a closing V. 





If the right argument Y is not a single well-formed 
name, or is not the name of a visible function, your 
attempt is rejected with the message 
DOMAIN ERROR. If the object named in the argu- 
ment of [JFD is indeed a visible function, but its 
definition is locked, the result is an empty vector. 


RACR Y Canonical representation of 
function named in Y 
R+-2 QFD Y 


Argument: A character vector (or scalar) con- 
taining the name of a visible function. 


Result: A character matrix containing the ca- 
nonical representation of the function. The canoni- 
cal representation doesn’t include leading and 
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trailing Vs; nor does it include line numbers. All 
lines are shown left-justified (that is, without any 
indentation). 


The matrix contains one row for the function 
header, and one row for each line of the definition. 
The number of columns is the length of the longest 
line. 


If a line of the definition contains a carriage return 
as a character constant, the carriage return is in- 
cluded in that row of the result. But neither DCR 
nor 2 DFD supplies six spaces after a carriage re- 
turn (whereas 1 DFD does). 


If you attempt to use 2 [DFD with a right argument 
that is not a valid name or is not the name of a 
function, the system rejects your attempt with the 
message DOMAIN ERROR. If you try 2 [FD with 
the name of a locked function, you get an empty 
matrix. 


The function DCR is more tolerant. If its argument 
is not a valid name, or is the name of something 
that is not a function, or is the name of a locked 
function, you simply get an empty matrix as the 
result. 


Fix a definition from the 
array Y 


ReFX Y 
Re3 DFD Y 


Argument: A character array containing the 
representation of a function. The function OFX re- 
quires that the representation be a matrix (such 
as the matrix produced by OCR). The matrix may 
not include line numbers, nor opening and closing 
V symbols. However, it doesn’t have to be left- 
justified. 


The function 3 [FD is more tolerant than DFX. 
For one thing, 3 [FD accepts a carriage return as 
a character constant, whereas DFX doesn’t. 


Unlike OFX, the function 3 OFD also accepts a 
representation in vector form. A vector representa- 
tion must include a leading and a closing V (or 
4). Each of its lines must be numbered, in the 
same way that they are in representations 
produced by 1 QFD. The line numbers must be a 
dense set of integers. That is, the first line must 
be line [1], the second must be line [2], and so 


on. You can’t use fractional line numbers, or num- 
bers that are out of order, or skip any line num- 
bers. 


If a vector representation used with 3 [FD con- 
tains a carriage return as an embedded character 
constant, the carriage return must be followed by 
six spaces (just as it is in the display produced by 
1 DFD). These spaces don’t become part of the 
definition, but serve to show that this carriage re- 
turn is part of the line rather than a line-separa- 
tor. 


Effect: A function is created. Its name is what- 
ever name is shown in the header line within the 
argument Y. 


When the argument is a vector and either of the 
opening or closing symbols is ¥ (del-tilde) rather 
than V (del), the new function’s definition is 
locked. 


The function that is created is a visible use of the 
name given in the header. If (at the moment the 
function is created) that name is local to a func- 
tion whose execution hasn’t been completed, then 
the newly-created function is a local function. 
That means that it will vanish when execution of 
the function to which it is local is completed. It 
also means that it can’t be edited with the V func- 
tion editor (which works only on global func- 
tions). 


When it’s permissible to fix a new function def- 
inition: When you're using 3 DFD, there must 
be no visible use of the name that the new func- 
tion is to have. If you’re doing this in order to 
revise the definition of a function already present 
in the workspace, you must first expunge that def- 
inition. The visible meaning of a name can be 
expunged with the function DEX or 6 DFD. 


When you’re using DFX, there must be no existing 
visible use of the function’s name as the name of 
a variable or a label. But you may create a new 
definition for an existing function provided that 
that function is not being executed (that is, provid- 
ed it doesn’t appear anywhere on the state indica- 
tor). 


Result: If your attempt to create a new function 
is successful, the result returned (whether by 
OFX or by 3 DFD) is a character vector containing 
the name of the function just created. 
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Meaning of diagnostic codes in the first ele- 
ment of a numeric return from 3 DFD: 


WS full: To create the proposed function 
would require more room in the workspace 
than is available. 


Definition error: The function’s name is 
in use; the function’s header is ill-formed; 
the vector argument lacks a leading and 
trailing V or ¥, or contains an extra one 
within the definition; the line-numbers are 
defective; the matrix argument contains a 
carriage return other than as a character 
constant. 


Character error: The argument contains 
a character other than those enterable from 
the keyboard or carriage return; the vector 
argument contains a carriage return that is 


neither a line delimiter nor followed by six 
blanks; the matrix argument contains a car- 
riage return inside a comment. 


Symbol table full: Fixing the function 
would require more new entries in the sym- 
bol table than are available. 


Unmatched quotes: The argument con- 
tains a line on which there is an odd num- 
ber of quotes other than quote marks ap- 
pearing inside a comment. 


Unused 


Empty line: The matrix argument con- 
tains a blank row; the vector argument con- 
tains a pair of line delimiters with nothing 
but blanks between them. 





If your attempt is unsuccessful, you'll still get a 
result. The result will instead be numeric. The 
function 3 [FD returns a 2-element numeric vec- 
tor, in which the first element is a code indicating 
what sort of problem was encountered, while the 
second indicates on which line of the proposed 
function the problem was encountered. The func- 
tion [JFX returns a numeric scalar, indicating the 
line on which trouble was encountered, but with- 
out additional diagnosis. 


REX Y 
Reo DFD Y 


Expunge objects named in Y 


Either of these may be used to expunge the visible 
functions or variables whose names appear in the 
argument Y. You can’t expunge a label, or a func- 
tion that is in use (that is, that appears on the 
state indicator). 


Watch out: You can get a similar effect using 
the system command )ERASE followed by the 
names of the objects you want to erase. However, 
the command )FRASE, like all system commands, 
can only be entered manually from the keyboard, 
and the names of the objects to be erased must also 
be entered manually. Moreover, the system com- 
mand )ERASE applies to the global meaning of 
each name, whereas the system function [EX and 
6 DFD refer to the visible (that is, most local) 
meaning. 





Argument: The argument of either function is 
a character array containing the names of the ob- 
jects to be expunged. 


Argument of DEX: The argument of DEX is ei- 
ther a character vector containing a single name, 
or a matrix containing no more than one name on 
each row. The function DEX doesn’t object to blank 
rows. 


Argument of 6 [JFD: The function 6 [QFD ac- 
cepts as its argument a namelist; that is, a charac- 
ter array in which names are arranged either as 
the rows of a matrix, or in a vector (or scalar). 
In either event, all the names must be valid names. 
If the argument contains something that couldn’t 
be the name of an APL object, the argument is 
rejected with the message [FD ERROR. When the 
argument is a vector, it may contain any number 
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of names separated by blanks. When the argument 
is a matrix, it must have one name on each row; 
it can’t include a blank row. 


Effect: The visible variables or functions named 
in the argument are expunged. If you try to refer 
to one, you’ll get the message VALUE ERROR or a 
SYNTAX ERROR, depending on the way you at- 
tempt to use the name. 


Result of DEX: A Boolean scalar or vector con- 
taining one element for each name to be expunged. 
The result is a scalar when the argument was a 
scalar or a vector, and a vector when the argument 
was a matrix. 


An element of the result contains a 1 where the 
corresponding member of the argument contains a 
valid name that has been freed. That could either 
be because the object named was successfully ex- 
punged, or because the name didn’t have any visi- 
ble use to begin with. 


An element of the result is 0 where the corre- 
sponding member of the argument is not a valid 
name now free for use. That could be either be- 
cause the name refers to an object that isn’t eligi- 
ble to be expunged, or because it isn’t a valid name 
at all. 


Result of 6 DFD: A character matrix containing 
all those names that could not be expunged. A 
completely successful use of 6 DFD thus results in 
an empty matrix. 


Lock definitions of functions 
named in Y 


R-7 DFD Y 


Argument of 7 QFD: The function 7 [FD ac- 
cepts as its argument a character array in which 
names are arranged either as the rows of a matrix, 
or in a vector (or scalar). In either event, all the 
names must be valid names. If the argument con- 
tains something that. couldn’t be the name of an 
APL object, the argument is rejected with the mes- 
sage DFD ERROR. 


When the argument to 7 DFD is a vector, it may 
contain any number of names separated by blanks. 
When the argument is a matrix, it must have one 
name on each row; it can’t include a blank row. 


Effect: The definitions of those visible functions 
whose names appear in Y are locked. That is, it 
is no longer possible to display their definitions. 


Result: A character matrix containing those 
names from Y whose visible use was not the name 
of a function (and for which, therefore, no action 
was taken). 


Stop and trace control 


The stop and trace controls permit you to modify 
a function’s definition so that work always halts 
before the execution of certain lines (“stop”), or 
the line’s effect is displayed after it has been exe- 
cuted (“trace”). These facilities are intended pri- 
marily as aids while you’re debugging a defective 
definition. When execution stops, you can examine 
intermediate results. From a trace, you get a dis- 
play showing the sequence in which lines were 
executed and the principal result of each state- 
ment. 


The syntax of stop and trace: The mechanism 
by which you mark lines in a function definition 
for “stop” or “trace” has been retained in SHARP 
APL much as it was in APL\360. The syntax of 
“stop” and “trace” is anomalous, and inconsistent 
with the rest of APL; probably at some future 
time there will be some more general and more 
consistent way of evoking such controls. 


To mark a function for stop or trace, you execute 
an expression involving <, the specification arrow. 
To the right of the arrow you write an expression 
whose value indicates which lines are to be 
marked. To the left of the arrow you write the 
name of the function to be marked, preceded by 
the prefix SA (to mark lines before which execu- 
tion is to stop) or TA (to mark lines whose execu- 
tion is to be traced). 


The characters that follow the prefix SA or TA 
must spell a name that already has a visible use 
in the workspace, and whose nameclass is “‘func- 
tion.” 


Example: To specify that an existing function 
called COMPUTE is to stop before each execution of 
lines 3 or 11, you write 


SACOMPUTE*3 11 
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Similarly, to trace execution of lines 4, 6, and 8 
of a function TEST, you write 


TATEST+4 6 8 


Stop and trace are independent: Using the 
prefix SA sets new stop controls, but has no effect 
on tracing. Conversely, using 7A sets new trace 
controls but has no effect on stopping. Any line 
in the body of a function can be marked with 
either, neither, or both “stop” and “trace.” 


“Domain” of stop and trace control: The 
value to the right of the specification arrow must 
be a numeric scalar or vector in which no element 
is a fraction. An element whose value isn’t the 
number of any line in the function is permissible, 
but has no effect. 


The name to the left of the specification arrow 
must be formed by attaching the prefix SA or TA 
to the name of a visible function. The system re- 
jects any other name with the message SYNTAX 
ERROR. 


Effect: Within the definition of the function 
whose name follows the prefix SA or TA, any 
previous stop controls (when the prefix is SA), 
or any previous trace controls (when the prefix is 
TA), are removed. Each line whose current line 
number is a member of the right argument of + 
is marked “stop? (when the prefix is SA) or 
“trace” (when the prefix is TA). 


Note that it is the line itself that gets marked, not 
its line number. If the line’s position is changed 
because other lines are inserted or deleted ahead 
of it, the line remains marked, even though it ac- 
quires a new line number. 


Once a function has been locked, its stop or trace 
controls cannot be altered. The system does not 
reject a statement purporting to change the control 
of a locked function, but ignores it. 


Result: The result is treated in the same way as 
the result of any assignment. That is, the result 
of « is the value to the right of the arrow. That 
permits you to use the result as the argument of 
another function; for example, you might want to 


use the result to set stop or trace controls on an- 
other function, or to assign them to a variable for 
re-use later. 


Behaviour of a function containing a line 
marked “stop”: Whenever the system is about 
to execute a line marked “stop,” it halts execution 
in much the same way that it would if you'd sig- 
nalled “attention” from the keyboard. The system 
reports that as event 1001, which is trappable. At 
the terminal, the system displays the name of the 
function and, beside it, the number of the line 
that’s next to be executed, in brackets. It does not 
display the line itself; nor does it display the event 
title, STOP; however, that title is included in 
DER. 


Resuming execution following a stop: A 
branch statement, either entered from the key- 
board or within a trap line, causes the system to 
resume execution at the line indicated by the desti- 
nation of the branch. In particular, the branch 
+(JLC causes execution to resume at the point 
where it was halted. 


Notice that a branch statement in a trap line, or 
entered from the keyboard, causes the system to 
resume execution at whatever line is indicated, re- 
gardless of whether that line is marked “stop.” 
Since event 1001 is trappable, the trap line can 
cause execution to resume immediately, with no 
halt detectable at the terminal. 


Behaviour of a function containing a line 
marked “trace”: The branch destination or re- 
sult of each statement on a line marked “trace” 
is displayed at the terminal. The display is pre- 
ceded by the name of the function, and the line 
number in brackets. 


A statement which has no result or causes no 
branch (for example, +10) appears in the display 
as a blank line. A branch which is taken is repre- 
sented in the display by the right arrow > followed 
by the destination, shown as a single numeric 
value. For example, if D is a variable having the 
value 3 17, the statement +D is reported in the 
trace as +3. 


A “naked branch” (a statement consisting of > 
alone) appears in the trace as > alone. 
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For each statement that is not a branch, the system 
displays the result of the root function. For exam- 
ple, if the statement is 


X*+2xY«o 


the root function is the specification at the left, 
whose result is 12. 


When you trace a statement which uses 0D or | 
output, that output appears before the display 
produced by tracing. If the statement’s root func- 
tion is the assignment to [] or [ (for example, in 
a statement such as [}#XxY), you'll see the same 
output twice, first as the effect of [+ or fk, and 
then as the trace of <. 


When a line contains several statements separated 
by diamonds, the trace shows the function name 
and line number preceding display of the first 
statement, and the symbol © preceding each dis- 
play from other statements on the same line. 


Packing or copying a function marked for 
“stop” or “trace”: If you copy the definition of 
a function from a saved workspace to your active 
workspace, or use [PACK to include a function 
definition in a package, the lines marked “stop” 
or “trace” are part of the definition, and are 
copied or packed with it. 


Record of which lines are marked: Although 
marking a line for “stop” or “trace” affects the 
way the line is recorded in the function’s defini- 
tion, it does not affect the function’s canonical rep- 
resentation, and does not appear in its display. 
Thus, there is no way to ask which of a function’s 
lines have been marked. In particular, the name 
which appeared to the left of the + (for example, 
SACOMPUTE when you set stop controls by 
SACOMPUTE*3 11) is not the name of an object 
in the workspace, and you can’t refer to a variable 
SACOMPUTE in order to find out where stops are 
set in the function COMPUTE. 


If you need to retain a record of the lines you have 
marked, it would be prudent to assign the result 
of the original specification to a variable, by a 
statement such as 


TRACED*«TACOMPUTE*+3 4 8 


Removing “stop” or “trace” markers: Each 
use of SA first removes any previous “stop” mark- 
ings, and then sets new ones according to the val- 
ues to the right of the specification arrow. Hence, 


SACOMPUTE+10 
removes all previous “stop” markings and sets no 
new ones, and thus has the effect of removing all 
stops from the function COMPUTE. 
Similarly, each use of TA removes any previously 
set “trace” markers before the system sets new 
ones, and so 


TACOMPUTE+1G 


turns off all tracing of lines in the function 


COMPUTE. 
$ 
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RHIAVAIL 10 File availability 


Argument: An empty vector. In effect, this is a 
niladic function. When it was designed, it was 
intended that DAVAIL would take an argument 
indicating which of several alternative file systems 
you were asking about. The SHARP APL file 
system subsequently evolved as a single integrated 
system, and so there are now no meaningful argu- 
ments other than the empty vector. 


Result: A Boolean scalar. Its value is 1 when the 
file system is available, and 0 when the file system 
is not available. This is the only file function 
which can be successfully executed when the file 
system is not running. 


R+QLIB Y File library of account Y 


Argument: A numeric scalar or 1-element vector 
indicating the number of an account; that is, the 
number of a user (when the number is 1000 or 
greater) or the number of a public library (when 
the number is between 1 and 999). 


Result: A character matrix containing the names 
of all those files to which you are permitted any 
access and which belong to library Y. 


The result contains one row for each such file, and 
22 columns. The first ten columns contain the 
character representation of the library number, 
right-justified. The next column is blank. The re- 
maining 11 columns contain the name of the file, 
left-justified. 


R<QNUMS Numbers of tied files 
ReQNAMES Names of tied files 


These are niladic functions. You can use them 
only to report on the current task. 
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Result of (UMS: An integer vector containing 
the tie numbers for those files now tied by this 
task. 


Result of DNAMES: A character matrix showing 
the names of files now tied by this task. 


The result has one row for each file that is tied, 
and 22 columns. The first 10 columns contain the 
character representation of the number of the ac- 
count that owns the file, right-justified. The next 
column is blank. The last eleven columns contain 
the names of the files, left-justifed. 


Provided you don’t create, tie, or untie a file be- 
tween using these two functions, they return their 
results in the same order. For a row in the result 
of DVAMES, the corresponding element in the result 
of (WUMS shows the number to which that file is 
tied. 


Share-tie file X to Y 
Exclusive-tie file X to Y 


X DSTIE Y 
Xx DTIE Y 


Right argument: An integer scalar, or a vector 
of one or two elements. 


The first (or only) element is the number pro- 
posed as a tie number for the file. It must be a 
positive integer that is less than 2*31 and one that 
is not now in use by this task as a tie number. 


Note that it doesn’t matter what the tie number 
is, provided only that: 


1. You choose a number that isn’t in use to tie 
some other file, and 


2. the applications that use the tie number are all 
aware of what it is. 


Watch out: It is poor practice to have the tie 
number appear as a constant in your programs. 
If you were to do that, you’d run the risk that a 
tie number used in one program will conflict with 
a tie number of some other program that you want 
to have running at the same time. It’s preferable 
to generate a tie number arbitrarily and then store 
it somewhere that the functions that require it can 
find it; for example, as a global variable in the 
workspace. You could also use a function which 


in effect refers to files by name, matching the 
name you propose with the result of OWAMES, and 
then selecting an appropriate element from 
OWUMS. Several utility functions to facilitate file 
tying may be found in the public libraries; for 
example, the public workspace 1 FILEAID. 


You could generate an arbitrary non-conflicting tie 
number by an expression such as 


TIENO+( (1 pUONUMS )€0,QNUMS ) 10 


Passnumber in right argument: If the right ar- 
gument Y has two elements, the second is the pass- 
number. When the argument is a scalar or 1- 
element vector, a passnumber of 0 is understood. 


Left argument: A character scalar or vector con- 
taining the name of an existing file. The first field 
of the left argument may contain the character 
representation of an account number. If you omit 
the account number, your own account is implied. 
To the right of the account number (if shown) 
and separated from it (if it’s present) by one or 
more blanks, is the name of the file. 


Permission: There is no specific permission code 
for OSTIE. If you have permission to use any other 
function with a file, you can also share-tie it. 
However, unless you’re the owner of the file, you 
need explicit permission to use the exclusive form 
OIE. To use QTIE, the permission code that the 
system selects from the access matrix when you tie 
the file must include the number 2. 


Limit on total number of files tied: The sys- 
tem imposes a limit on the total number of files 
that one can have tied simultaneously. At present, 
the limit is twenty files. If you attempt to tie more 
files than that limit, the system rejects the state- 
ment with the message FILE TIE QUOTA 
USED UP. There is also an upper limit to the 
number of distinct files that can be simultaneously 
tied (by all tasks); if your attempt to tie would 
exceed the system’s capacity, the statement is re- 
jected with the message FILE SYSTEM TIES 
USED UP. 
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Effect of (STIE: The file identified by X is tied 
to the number included as the first element of Y 
if all of the following conditions are met: 


1. The file exists. 


2. Its access matrix contains a row matching both 
the passnumber you used and your user number, 
or, failing that, the passnumber you used and user 
number 0. 


3. The permission code on the first such row of 
the access matrix is a number other than 0. 


4. No other user now has the file exclusively tied. 


When the file is share-tied, the fact that you have 
tied it does not prevent another task from share- 
tying it also. That’s the meaning of share-tying: 
that your tie is not exclusive, and does not prevent 
others from share-tying the same file at the same 
time (provided, of course, that they have the nec- 
essary permission). 


Effect of DTIE: The file identified by X is tied 
to the number included as the first element of Y 
if the following conditions are met: 


1. The file exists. 


2. Its access matrix contains a row matching both 
the passnumber you used and your user number, 
or, failing that, the passnumber you used and the 
user number 0. 


3. The permission code on the first such row of 
the access matrix includes the number 2. 


4. No other user has the file tied at all, either 
share-tied or exclusive-tied. 


Once you have exclusively tied the file, until you 
untie it, no other user can tie it at all, neither 
share-tie it nor exclusive tie it. 


Result: None. Since neither TIE nor (STIE re- 
turns a result, either of them can appear only as 
the root function of the statement in which it is 
used. 


DUNTIE Y Untie files tied to Y 
Argument: An integer scalar or vector of tie 
numbers of tied files. 


Permission: None is required. 


Passnumber: Passnumbers don’t apply to 
OUNTIE. You don’t use a passnumber even if you 
did use one to tie the file. Any number appearing 
in the right argument Y is assumed to represent 
a tie number. 


Effect: The files whose tie numbers appear in 
Y are untied. However, if any of the elements of 
Y is not a valid tie number, the system rejects the 
entire expression with the message FILE TIE 
ERROR. 


Once you’ve untied a file, use of that tie number 
in the argument of a file function is rejected with 
the message FILE TIE ERROR. There’s no way to 
refer to the files that were untied until you subse- 
quently re-tie them. 


R-X QAPPENDR Y Append X 
to the file tied to Y 
X [APPEND Y 


Right argument: An integer scalar or a vector 
of one or two elements. The first (or only) ele- 
ment of the right argument contains the tie num- 
ber of a tied file. If you used a non-zero passnum- 
ber when you tied the file, that passnumber must 
appear as the second element. 


Left argument: A data object (that is, a rectan- 
gular array or a package). 


Permission: To use either [JAPPENDR or 
[APPEND with a particular file, the permission 
code that the system selected from the access ma- 
trix at the time you tied the file must include the 
number 16384 for DAPPENDR or 8 for DAPPEND. 


Effect: Provided that the number of bytes the 
file already occupies is less than the file’s reserva- 
tion limit, a new component is appended to the file 
tied to Y. That component contains the data object 
X, together with its data description, which speci- 
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fies the type, rank, and shape of the data. The 
component also contains control information in- 
dicating the number of bytes of storage that the 
component requires, the account number of the 
person whose task appended the new component, 
and a timestamp (see the description of ỌRDCI). 


Result of [APPENDR: The result is an integer 
scalar containing the component number of the 
newly appended component. 


Result of APPEND: None. Since [APPEND re- 
turns no result, it can appear only as the root 
function of the statement in which it is used. 


R+(\READ Y Read a component of file tied 


to the first element of Y 


Argument: An integer vector of two or three ele- 
ments. 


The first element contains the tie number of a tied 
file. 


The second element contains the number of an 
existing component within that file. (If a compo- 
nent exists, its component number is less than the 
second element of the result of OSZZE, but not less 
than the first.) The system rejects an attempt to 
refer to a non-existent file component with the 
message FILE INDEX ERROR. 


If you used a non-zero passnumber when you tied 
the file, that passnumber must appear as the third 
element of the right argument. 


Permission: To use [DREAD with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 1. 


Result: The data object stored in the indicated 
file component. 


X OREPLACE Y Replace with X the file com- 
ponent indicated in Y 


Right argument: An integer vector of two or 
three elements. 


The first element contains the tie number of a tied 
file. 


The second element contains the number of an 
existing component within that file; see the discus- 
sion of the second element of the argument of 
LIREAD. 


If you used a non-zero passnumber when you tied 
the file, that passnumber must appear as the third 
element of the right argument. 


Left argument: A data object. That is, a rectan- 
gular array or a package. 


Permission: To use [REPLACE with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 16. f 


Effect: The data object formerly stored as that 
component of the file is replaced by the new data 
object. 


For the system to make the replacement, either of 
the following must be true: 


1. The storage already in use for the file does not 
exceed the files reservation (that is, 
</2+24+0SIZE Y) 


or 


2. The new component requires no more space 
than the old one. 


Following a successful replacement, the component 
contains the data itself, together with a data de- 
scription indicating the type, rank, and shape of 
the data. It also contains control information in- 
dicating the number of bytes required to store the 
object, the account number of the person whose 
task did the replacement, and a timestamp indicat- 
ing the date and time at which the replacement 
took place; see the description of QRDCT. 


Result: None. Since DREPLACE returns no re- 
sult, it can appear only as the root function of the 
statement in which it is used. 
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X OCREATE Y Create file X share-tied to Y 











Right argument: A scalar or 1-element vector 
containing a positive integer less than 2*31 that 
is not now in use as a tie number. You can’t use 
a passnumber to create a file. 


Left argument: A character vector or scalar con- 
taining the name of the proposed new file. 


The left argument X is divided into three fields 
(two of which may be omitted), separated by one 
or more blanks. The fields are: 


1. Character representation of the number of the 
account that is to own the file. This must be either 
your own account number, or the number of a 
public library; you can’t create a file in someone 
else’s private file library. 


This field may be omitted; in that case, your own 
number is understood. 


2. Name of the proposed new file. The name may 
consist of up to 11 alphanumeric characters, and 
must start with an alphabetic character. It may not 
contain an embedded blank, period, or any other 
of the special symbols. It must be a name not now 
in use as the name of a file in the library you 
specified. 


This field may not be omitted. 


3. File limit. The number of bytes beyond which 
you will not be permitted to enlarge the file by 
appending new components or by replacing exist- 
ing ones. 


This field may be omitted. If so, the system sup- 
plies for you its default file limit, which at present 
is 100992 bytes. If you state a limit as part of the 
left argument of CREATE, it must be in integer 
format—that is, to reserve a million bytes, you 
must use the characters 1000000 rather than 
126. 


Permission: Not applicable. 


Effect: Provided that the arguments are valid, a 
new file is created. The new file has no compo- 
nents. Its access matrix is a 0-by-3 numeric ma- 
trix, meaning that its owner has unlimited access 


to it, and no one else has any. See the section 
headed “Control of Access to a File” and the ensu- 
ing discussion of the access matrix. 


The new file is share-tied to the number indicated 
in the right argument. 


Result: None. Since QCREATE has no result, it 
can appear only as the root function of the state- 
ment in which it is used. 


Rename to X the file tied to 
Y 


X ORENAME Y 


Right argument: An integer scalar or vector. 
The first element contains the tie number of a tied 
file. If you used a non-zero passnumber when you 
tied the file, that passnumber must appear as the 
second element of the right argument. 


Left argument: The new name proposed for the 
file. The left argument of RENAME is governed by 
the same rules as the left argument of (CREATE. 
The name is limited to alphanumeric characters. 
It may be preceded by an account number, but 
only to indicate your own account or that of a 
public library. The name must be one not now in 
use in that library as the name of a file. 


Permission: To use [RENAME with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 128. 


Effect: The file is renamed as indicated. It now 
belongs either to your file library, or to the public 
file library you indicated in the left argument. 
Either way, you are now the owner of the file. 


The file’s reservation is transferred from the form- 
er owner’s account to yours. If your file reserva- 
tion limit is insufficient, the system rejects the 
statement with the message FILE RESERVATION 
ERROR. 


You can’t use [RENAME to transfer a file to some- 
one else’s private library. If you want to give a file 
to someone else, you must first give that person 
permission to RENAME the file, and then that per- 
son may rename it. 
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Result: None. Since (RENAME returns no result, 
it can appear only as the root function of the 
statement in which it is used. 


X DERASE Y Erase the file whose name is 


X and is tied to Y 


Right argument: A numeric scalar or vector, 
containing the tie number of the file. If you used 
a non-zero passnumber when you tied the file, it 
must appear as the second element of the right 
argument. 


Left argument: A character vector or scalar con- 
taining the name of the file to be erased. If you 
aren’t the owner of the file, the character represen- 
tation of the owner’s account number must precede 
the file name, separated from it by a blank. The 
left argument is redundant: all this information is 
available simply from the tie number. The system 
requires you to provide both forms of identification 
to make it less likely that you’ll inadvertently erase 
the wrong file. 


Permission code: To use DERASE with a partic- 
ular file, the permission code that the system se- 
lected from the access matrix at the time you tied 
the file must include the number 4. 


Effect: The file ceases to exist. The number for- 
merly used to tie it is again free. The file’s name 
disappears from the result of QWUMS, of QNAMES, 
and of (ZLIB with respect to its library number. 
The file’s space and reservation are freed. 


Result: None. Since [ERASE returns no result, 
it can be used only as the root function of the 
statement in which it appears. 





RSIZE Y Size of file tied to Y 











Argument: An integer scalar or vector, contain- 
ing the tie number of a tied file. If you used a 
non-zero passnumber to tie the file, that passnum- 
ber must appear as the second element of the argu- 
ment. 


Permission: To use ỌSIZE with a particular 
file, the permission code that the system selected 


from the access matrix at the time you tied the file 
must include the number 1, which also gives per- 
mission to use DREAD. 


Result: A 4-element integer vector describing the 
size of the file now tied to the first element of 
Y. The four elements of the result have signifi- 
cance as follows: 


1. Lowest component number for this file (that 
is, 1 for a file from which no leading components 


have been dropped). 


2. Number of next component to be appended 
(that is, 1 more than the number of the last exist- 
ing component). 


3. Space now occupied by the file, in bytes. 
4. File reservation, in bytes. 


If Y is the tie number of a newly-created (and 
therefore empty) file, having the current default 
limit of 100992 bytes, then its size would be re- 
ported thus: 


OSIZE Y 
1 1 0 100992 


The number of components in the file tied to Y 
is given by 


--/2+Q)SIZE Y 


X DRESIZE Y Resize to X reservation of file 
tied to Y 


Right argument: An integer scalar or a vector. 
Its first element contains the tie number of a tied 
file. If you used a non-zero passnumber to tie the 
file, that passnumber must appear as the second 
element of the right argument. 


Left argument: An integer scalar or 1-element 
vector. Its value can’t be less than the present 
actual size of the file, nor so great that the sum 
of the reservations of all the files of which you are 
the owner would exceed your reservation limit. 
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Permission: To use QRESIZE with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 1024. 


Effect: The file’s reservation is revised as indi- 
cated. 


Result: None. Since DRESIZE returns no result, 
it can appear only as the root function of the 
statement in which it is used. 


QDROP Y Drop components from file Y 
You can drop a block of consecutive components 
either from the beginning or from the end of a file. 
That reduces the range of valid component num- 
bers. Suppose a file has 100 components, num- 
bered from 1 to 100. If you drop the last 10, it 
will then have 90 components, with numbers run- 
ning from 1 to 90. But if you drop the first 10, 
it will have 90 components with numbers running 
from 11 to 100. Dropping components from a file 
does not alter the numbers by which you refer to 
the components that remain. 


Argument: An integer vector of two or three ele- 
ments. 


The first element contains the tie number of a tied 
file. 


The absolute value of the second element indicates 
the number of components you want to drop. If 
the number is positive, they’re to be dropped from 
the beginning of the file. If the number is negative, 
they’re to be dropped from the end of the file. If 
you attempt to drop more components than exist, 
the system rejects the expression with the message 
FILE INDEX ERROR. 


If you used a non-zero passnumber when you tied 
the file, that passnumber must appear as the argu- 
ment’s third element. 


Permission: To use [DROP with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 32. 


Effect: The indicated number of components is 
dropped from the file. 


Result: None. Since (DROP returns no result, it 
can appear only as the root function of the state- 
ment in which it is used. 


Read access matrix of the file 
tied to Y 


Re{\RDAC Y 


Argument: An integer scalar or vector. If you 
used a non-zero passnumber to tie the file, that 
passnumber must appear as the second element of 
the right argument. 


Permission: To use [JADAC with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 256 or 4096. 


Result: The access matrix for the file tied to 
Y. An access matrix consists of three columns, in 
which the first is a user number, the second a 
permission code, and the last a passnumber. The 
significance of the access matrix is discussed in the 
section headed “Control of Access to a File.” 


Set to X the access matrix of 
the file tied to Y 


X (STAC Y 


Right argument: An integer scalar or vector. 
The first element of the right argument contains 
the tie number of a tied file. If you used a non- 
zero passnumber when you tied the file, that pass- 
number must appear as the second element of the 
right argument. 


Left argument: A three-column integer matrix. 
The system requires that the matrix have this 
form, but does not verify that the values in it are 
valid. 


Permission: To use [STAC with a particular 
file, the permission code that the system selected 
from the access matrix at the time you tied the file 
must include the number 256 or 8192. 
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File functions to which permission codes give access 
m syussesasheneeseessss 


DREAD OSIZE OSTIE 
OTIe OSTIE 
DERASE OSTIE 
DAPPEND OSTIE 
OREPLACE DSTIE 
DODROP USTIE 
DHOLD OSTIE 
OREWAME OSTIE 
DRDAC DOSTAC USTIE 
ORDCI OSTIE 
ORESIZE (SIZE OSTIE 
OFHOLD OSTIE 
ORDAC OSTIE 
OSTAC OSTIE 
DAPPENDR OSTIE 








No permission is needed to use the function JLIB. The result contains the names of those files 
which you own as well as the names of those whose access matrices give you any permission. 


Permission codes for file functions 
SS RY TS 


DAPPEND 8 
DAPPENDR 16384 
Not applicable 
Not applicable 
32 
4 
2048 
64 
* 
Not applicable 
Not applicable 
256 4096 
512 
1 
128 
OREPLACE 16 
ORESIZE 1024 
OSIZE 1 1024 
OSTAC 256 8192 
OSTIE Any of the other permissions also permits this. 
OTIE 2 
DUNTIE None needed (but you can only use it with respect to a file you’ve tied). 





*It is always permissible to use ỌZZB, but the result includes only those files which you own 
or to which the access matrix grants you some sort of access. 
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Effect: The left argument X becomes the access 
matrix for the file tied to Y. The system re-evalu- 
ates the permission of all tasks which currently 
have this file tied; your change to the access matrix 
takes effect immediately, even for tasks which had 
already tied the file. 


Watch out: If you use [STAC in such a way that 
you exclude yourself from (JSTAC access to the file, 
you can’t do another (STAC to restore it. If you 
have locked yourself out of access to a file that you 
own (i.e. which is part of your own private li- 
brary, or which you created or renamed to a pub- 
lic library), the system Operator can assist you; 
see the discussion of the file access matrix. 


Result: None. Since DOSTAC returns no result, it 
can appear only as the root function of the state- 
ment in which it is used. 


RRDCI Y Read control information 
from file component Y 


Argument: An integer vector of either 2 or 3 
elements. The first contains the tie number of a 
tied file. The second is the number of a particular 
component in that file. If you used a non-zero 
passnumber to tie the file, there must also be a 
third element containing that passnumber. 


Result: A numeric vector of control information 
for the indicated file component. At present it has 
three elements, with significance as follows: 


1. Size of the file component in bytes, including 
both the data and the data description which speci- 
fies its type, rank, and shape. 


2. Account number of the person whose task 
wrote the current value of the component. 


3. Timestamp showing when the current value of 
the component was written. 


The third element of ỌRDCI represents the system 
timestamp as sixtieths of a second since 0:00 
hours on 1 March 1960. Functions to assist the 
use of files may be found in workspace 
1 FILEAID; the function FTT in workspace 1 TS 
converts a single [JRDCI timestamp to conventional 
form. 


Converting time and date representations: A 
representation of the date and time in the form 
used in [IRDCI is obtainable from functions in 
workspace 1 FILEAID and 1 TS. 


OFHOLD Y Hold files tied to Y 


OHOLD Y 


These functions provide a way in which two or 
more tasks running at the same time can coordi- 
nate their use of files that they share. The function 
CHOLD behaves just as OFHOLD does, except that 
CHOLD has no provision for you to use passnum- 
bers, whereas [FHOLD uses a passnumber (which 
may be zero, either because you explicitly use a 
passnumber of 0 or because you omit mention of 
the passnumber ). 


When several tasks work on the same files at the 
same time, certain of their activities (but by no 
means all) have to be isolated. Certain activities 
are sensitive. Once you’ve started such an activity, 
you need to complete it without the risk that one 
of the other tasks will do something that interferes. 


Here’s a simple example. Suppose you have a pro- 
gram that reads a table from a file, alters some 
of the entries, and then puts it back. If two tasks 
do that at the same time, one update may over- 
write the other; the update written later may be 
in ignorance of the one completed just before it. 
So you need assurance that no one else tries to do 
the same sort of thing at the same time. You need 
to isolate each sensitive activity so that: 


1. You don’t start it while someone else is engaged 
in something that might conflict. 


2. Once you do start, no one else can start a po- 
tentially conflicting activity until you’ve finished. 


The file-holding functions OFHOLD and DHOLD give 
you a way to set up such protections. However, 
what you get is not a guarantee, but rather a set 
of tools to facilitate voluntary restraint. The hold, 
functions give you a way to make your task wait 
until other sensitive work is done, and a way to 
signal cooperating tasks that you need exclusive 
use of the files. Other tasks will respect your re- 
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quest for exclusive use if they use the hold func- 
tions appropriately. The hold functions do not 
assure you that you have the files to yourself; only 
the exclusive tie function QTIE can do that. It’s 
your responsibility as application designer to be 
sure that you’ve identified the various sensitive 
parts of your procedures, and isolated each of them 
with appropriate use of the hold functions. 


Argument: An integer array containing distinct 
tie numbers of all the files that you wish to hold. 


If you used a non-zero passnumber to tie any of 
those files, then you must use [JFHOLD rather than 
QHOLD, and the argument must be a 2-row matrix. 
The top row contains the tie numbers and the 
second row the corresponding passnumbers. The 
passnumber of a file that was tied without explic- 
itly stating a passnumber is 0. 


If you didn’t use passnumbers when you tied the 
files, then the argument may be a vector, or (if 
you’re only holding one file), a scalar. The func- 
tion QF HOLD will also accept a 1-row matrix. 


Permission: The permission code that the sys- 
tem selected from the access matrix at the time you 
tied each of the files that you now wish to hold 
must include the number 2048 for DFHOLD or 
64 for QHOLD. 


Effect: Using either of the hold functions has the 
following effects: 


1. Your preceding hold (if any) is released. It 
doesn’t matter whether the new request to hold 
applies to the same files or to different ones. Each 
use of either of the hold functions cancels any 
preceding use. 


2. Execution of your task goes into an indefinite 
delay until all the files you have asked to hold are 
free of holds by any other task. The system doesn’t 
provide any way to know whether a file is tied by 
another task, and hence there’s no way to know 
in advance how much delay your task will encoun- 
ter, or whether it will be delayed at all. From a 
terminal, you can use BREAK or ATTN to signal 
an interrupt. If the interrupt is not trapped, that 
returns control to the keyboard, and cancels the 
request to hold. But an interrupt that is successful- 
ly trapped does not break the hold. 


ann 


3. Once all the files you have requested are free, 
your hold takes effect. Execution of your task pro- 
ceeds. 


If the system receives from another task a request 
to hold any of the files you’re holding, that task 
will go into an indefinite delay until either you 
release your hold or you untie the files that the 
other task has asked for. 


Ending a file hold: A file hold, once in effect, 
is ended by any of the following: 


1. Another file hold. If you want to end the one 
now in effect, but not to issue a new hold, use 
either of the hold functions with an empty argu- 
ment. 


2. Untying the files. If you untie some but not all 
of the files you are holding, the hold remains in 
effect for those that are still tied. However, those 
that you untie are free to be tied by another task. 


3. The end of your task. An N-task or B-task is 
ended when it reaches a normal end, or when it 
encounters an error. A T-task is ended when you 
sign off, or as a consequence of a communications 
failure (“line drop”). Any task can be ended by 
being “bounced” by its owner or by the system 
Operator. 


4. Any untrapped error or interrupt. 


5. Any return to immediate execution (including 
one trapped as event 2001, since the only actions 
possible with event 2001 lead ultimately to imme- 
diate execution). 


You might return to immediate execution because 
the defined function that issued the hold has come 
to a normal end. Or you might return to immedi- 
ate execution because the system encounters an 
error, or because you signalled an interrupt by 


pressing BREAK or ATTN. 


Watch out: You can’t experiment with file holds 
by entering statements one after another in imme- 
diate execution mode. Any hold you enter that way 
terminates immediately when the system returns 
for the next entry from the keyboard. In that situ- 
ation, the most you could do would be to put into 
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a single line of entry (separated by diamonds), 
both the file hold and the statement you want 
executed during the hold. 


When the system returns to the keyboard to re- 
ceive [ or [ input, that does not constitute a return 
to immediate execution mode, and does not termi- 
nate a hold. 


Normal use of file hold: File holds are used to 
isolate a segment of sensitive code. They’ll there- 
fore occur inside the definition of a defined func- 
tion, in a sequence something like this: 


V FUNCTION ... 
[1] 
[2] E 
[3] DOFHOLD Y 
Cu] Sensitive code 
[5]  QFHOLD '' 
[6] sk 


It is good programming practice to minimize the 
elapsed time during which a file hold will be in 
effect. Compare the two examples that follow. In 
the first, the request for input occurs inside the 
hold, whereas in the second, the hold does not 
occur until the request for input has been satisfied. 


Not good 


OFHOLD Y 
( (DREAD Y,X), DFIN) OREPLACE Y,X 
OFHOLD 10 


Better 


T-0FI M 

OFHOLD Y 

( (DREAD Y,X),T) OREPLACE Y,X 
OFHOLD 10 


Note also that DHOLD can be used to synchronize 
activities other than file operations. For example, 
two tasks which each want to bounce the other 
might use 


DHOLD Y 


OBOUNCE 14QORUNST 31] 
DFHOLD 10 


where Y is some mutually agreed-on file. 


Watch out: Inside the block spanned by your 
initial hold and the subsequent release, your “sen- 
sitive code” must not invoke a function which itself 
uses a file hold. If you did that, the function you 
called would undo your earlier file hold when it 
issued its own. For this reason, a utility function 
shouldn’t use file holds, or, if it does, should in- 
clude a warning that using it will invalidate holds 
issued by the program that calls it. 


Result: None. Since neither JFHOLD nor HOLD 


returns a result, either of them can appear only 
as the root function of the statement in which it 


is used. 
$ 
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Chapter 25: 


SYSTEM FUNCTIONS 
FOR REPORTING 
SYSTEM OR 
WORKSPACE 
INFORMATION 





RAI Account information 


This is a niladic function. It describes the status 
of the user’s account. Note, however, that it does 
not include either current or cumulative data re- 
garding N-tasks or B-tasks. 


Result: An integer vector which currently has 
nine elements. You shouldn’t write applications 
that assume nine elements; DAT might be extended. 
The significance of the nine elements is as follows: 


1. Account number of the owner of the task 


2. Accumulated CPU units for this task, in milli- 
units 


3. Accumulated connect time for this task, in mil- 
liseconds 


4. Accumulated keying time for this task in milli- 
seconds (applies only to a T-task) 


5. Accumulated number of characters transmitted 
to or from this task (applies only to a T-task) 


6. Accumulated CPU units on T-tasks since the 
last billing, in milliunits 


7. Accumulated connect time on T-tasks since the 
last billing, in milliseconds 


8. Unused; contains the value 0 


9. Accumulated characters transmitted during T- 
tasks since the last billing 
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Note that the character count includes the trans- 
mission of blanks, and also of terminal control 
characters, some of which may have no visible 
effect on the display. These would include such 
characters as tabs, or the idles that are used to 
produce a delay to allow time at the terminal for 
repositioning the paper or the typehead. 


RLC Line counter 


This is a niladic function. It reports the current 
value of the line counter in the active workspace. 


Result: An integer vector. The result shows the 
number of the line now being executed, or next 
to be executed, in each of the defined functions 
whose execution has been started but not com- 


pleted. 


The vector resulting from DLC has one element for 
each row of the state indicator. (The state indica- 
tor is the result of 2 DWS 2, or you can display 
it by the command )SI.) 


The first element of the result of [ZC is the line 
now in execution, or during which execution was 
interrupted. When execution is halted at comple- 
tion of a line (for example, by an attention signal 
or in response to a stop vector), the first element 
of OZC is the number of the line next to be exe- 
cuted if execution is resumed in sequence. 


Watch out: If execution was halted in the mid- 
dle of a line, the first element of DLC contains the 
number of the line during which work was halted. 
However, >[JLC would cause an attempt to execute 
that line again from the beginning. If the line 
both uses and respecifies the value of a variable 
or file component, it may be impossible to re- 
execute it correctly. 


The primitives 0 and # appear on the state indica- 
tor in the same way as defined functions. Where 
one of these occurs in the state indicator, the corre- 
sponding element of DEC is 0. 


RANC Y 


Nameclass of objects named 
Y 


Argument: A character array containing the 
names of objects. In general, the array is a matrix 
with one name on each row. There may be any 
number of leading or trailing blanks on any row, 
but a row can’t be entirely blank. If the array 
contains only one name, it may be either a 1-row 
matrix, a vector, or (if its name contains only one 
character), a scalar. 


Result: An integer vector containing one element 
for each of the names in the argument Y. The 
elements of the result describe the class which de- 
scribes the visible (that is, most local) use of each 
name. The classes are as follows: 


0 A well-formed name with no visible use 

1 Visible use as a label 

2 Visible use as the name of a variable 

3 Visible use as the name of a function 

4 Other (including an ill-formed name, or use 


as the name of a group) 


The result returned by ONC is similar to that re- 
turned by 5 [WS Y. However, DNC reports only 
the visible use, whereas 5 [WS reports the use at 
every level of the state indicator, and hence may 
include uses that are not currently visible. 


The result of 5 [WS uses an encoding scheme dif- 
ferent from that used for ONC. The two encodings 
are compared in the discussion of (W5. 


Re DNL Y 
ReX (NL Y 


Namelist of objects in class Y 
Namelist of objects in class Y 
whose names begin with 
characters in X 


Right argument: An integer vector or scalar 
limited to any of the numbers 1 2 3, in any 
order. 


The integer(s) in the right argument indicate the 
class (or classes) of objects you’re interested in. 
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Classes of objects are designated by the following 
code, which is a subset of the codes returned by 
ONC: 


1 Visible use as a label 
2 Visible use as the name of a variable 
3 Visible use as the name of a function 


Note that these codes differ from those returned 
by 5 DWS Y, or used in the argument of 
1 (WS Y. The encodings are compared in a table 
included with the definition of DWS. 


Left argument: If present, a character scalar or 
vector, whose elements are alphabetics (that is, A 
-Z, A-Z, or A or A). 


Result: A character matrix of names. There is 
one row for each distinct name, and as many col- 
umns as necessary to accommodate the longest 
name. 


A name appears in the result if: 


1. It is the name of a visible object in the work- 
space 


and 


2. The object is a member of one of the classes 
indicated by the argument Y 


and 


3. When there is a left argument, the first charac- 
ter of the name is a member of X. 


Names appear in the result left-justified, with 
trailing blanks. They are in an arbitrary order, 
unrelated both to their spelling and to the class of 
object to which each refers. 


RTS Timestamp 


This is a niladic function. It reports the current 
time and date according to the system’s clock. 


Result: An integer vector of seven elements, with 
meaning as follows: 


1. Year; note that the year is reported in full; 
1962 rather than 62. 


2. Month 
3. Day 


4. Hours since midnight; note that the hour fol- 
lowing 12 is 13. 


5. Minute 
6. Second 
7. Millisecond 


On the system operated by I.P. Sharp Associates 
at Toronto, the date and time are recorded in coor- 
dinated universal time (UTC), which is the inter- 
national time standard. 


RQUL User load 


This niladic function reports the number of users 
the system currently has signed on. 


Result: An integer scalar containing the total 
number of tasks currently running. This includes 
T-tasks, N-tasks, and B-tasks while they are actu- 
ally running. In addition to tasks submitted by 
users, a small number of these will usually repre- 
sent tasks run by the system Operator. 


RWA Work area remaining 


This niladic function reports the remaining free 
space in the active workspace. 


Result: An integer scalar reporting the amount 
of free space in the workspace, in bytes. Space is 
required in the workspace for each of the APL 
objects it contains, and also for the state indicator 
and the symbol table. Space is also required for 
all intermediate results generated during calcula- 
tion. 
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m_s 


R-X (WS Y Workspace information 

This dyadic function is capable of returning sever- 
al different reports on the workspace environment. 
It takes as its left argument one of the the integers 
from 1 to 6. Which of those you choose determines 
which of several reports is returned. In what fol- 
lows, there is a separate description for each of the 
six values of the left argument. 


Left argument: A scalar or a 1-element vector, 
having one of the values 4 2 3 4 5 6. The value 
of the left argument has significance as follows: 


Namelist of visible objects in class 
Y 


Workspace ID 

State indicator 

Workspace environment 
Workspace size, ownership, and 
timestamp 


Namelist of members of group 
named in Y 


Space required for visible objects 
named in Y 


Nameclass at each level of state in- 
dicator for objects named in Y 


Value of variable named in Y 





R+1 (WS Y Namelist of visible objects in 


class Y 


Right argument: An integer scalar or 1-element 
vector indicating the class or classes of objects 
whose names are to be reported. Each of the codes 
designating a class of object is a power of 2. The 
codes are as follows: 


1 Functions 


2 Variables 


4 Groups 


8 Labels 


When you want a report of names in any of sever- 
al classes, you form the right argument as the sum 
of the codes for the classes you want. Thus, to get 
both “functions” (code 1) and “variables” (code 
2), you’d use 1 [WS 3. 


In interpreting the right argument, the system 
looks at its base-2 representation. Any number 
whose base-2 representation contains a 1 in the 
last position, is interpreted to mean that the result 
should include the names of functions. Similarly, 
any number whose base-2 representation contains 
a 1 in next-to-last position, is interpreted to mean 
that the result should include the names of varia- 
bles, and so on for the other two classes that may 
be reported. 


Result: A character matrix containing the names 
of visible objects that are members of any of the 
classes mentioned in the right argument. The re- 
sult contains one row for each name, and as many 
columns as necessary to accommodate the longest 
name. Each name appears left-justified within its 
row, with trailing blanks if necessary. The rows 
are arranged in alphabetical order. 


Comparison of [WL Y and 1 [WS Y: The en- 
coding used by [WS was introduced first; IBM 
subsequently introduced the classification used for 
ONZ. SHARP APL supports both. 


The two definitions differ primarily in the way in 
which they encode the class of objects you want 
reported. With DNZ, to indicate several classes, you 
make the argument a vector containing the code 
for each of the classes you want. With 1 WS, the 
argument is always a single number, but may be 
formed by summing the codes for the distinct class- 
es. To make the codes summable, 1 [WS uses 
codes that are powers of 2. Codes for the two 
purposes are as follows: 
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ONL 1 WS 
(Combine by (Combine by 
Class catenating ) adding) 


Functions 3 
Variables 2 


Labels 1 


Other tu 
(i.e. Groups) 


The two functions also differ in the following re- 
spect: the result of 1 [WS Y is returned in alpha- 
betical order, whereas the result of DNZ Y is not. 


R2 OWS 1 Workspace info: WS ID 
Result: A character vector containing the current 
name of the active workspace. 


If the workspace has not been named (by )WSID 
or )SAVE), the result is an empty vector. But if 
the workspace has been named, the result is a 
vector of 22 characters. The first 10 elements con- 
tain the character representation of the library 
number, right-justified. The next character is 
blank. The remaining 11 characters contain the 
name of the workspace, left-justified, with trailing 
blanks if necessary. The result does not indicate 
whether the workspace has a password. 


Re2 [WS 2 Workspace information: state 


indicator 


Result: A character matrix showing the name of 
each function whose execution has been started but 
not completed. To the right of each function name, 
appears the number of the line being executed or 
next to be executed, in brackets. Each line that 
describes a function whose execution is suspended 
is marked with an asterisk. The asterisk appears 
to the right of the closing bracket, separated from 
it by one space. 


The functions are listed in chronological order, 
with the most recent at the top. 





You can produce a display identical in appearance 
to the result of 2 [WS 2 by the system command 
)SI. The use of 2 [WS 2 is also discussed in the 
chapter entitled “The Workspace Environment.” 


Example showing state indicator and line coun- 
ter: The following example illustrates the se- 
quence in which functions are reported in the state 
indicator. Suppose that from the keyboard you in- 
voke a function called UPDATE. On its fifth line, 
UPDATE invokes a function called ENTER, which, 
in turn, on its second line, invokes a function 
VERIFY. 


Now suppose that while it’s executing line 3 of 
VERIFY, the system encounters an error. Execu- 
tion is suspended. 


Now suppose that before deciding what to do 
about that error, you start a new execution (leav- 
ing the earlier work suspended). You invoke the 
function REPORT. In its sixth line, REPORT invokes 
a function called SUMMARIZE, whose first line in- 
vokes a function called EXTRACT, whose third line 
invokes a function called LOCATE. During execu- 
tion of line 1 of LOCATE, the system encounters 
another error. Execution is again suspended. 


Now you’ve got two functions suspended, and five 
others pendent. 


Suppose now you want a detailed report of this 
situation. You can get it by using the system func- 
tion 2 [WS 2 or by the system command )SI. 
Executing 2 [WS 2 gives you a seven-row sum- 
mary of this state of affairs, as follows: 


2 WS 2 
LOCATE[1] * 
EXTRACT([ 3] 
SUMMARIZE[1] 
REPORT(6] 
VERIFY[3] * 
ENTER[ 2) 
UPDATE[5] 


You could also get the line numbers (which ap- 
pear on each row, enclosed in brackets) as the 
result of the system function DZC: 


OLC 
1316325 
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R+2 [WS 3 Workspace environment 
Result: An integer vector that at present con- 
tains twelve elements, describing certain aspects of 
the active task and the active workspace. 


When this function was designed, it provided the 
only way that a program could inquire about the 
current value of such things as the index origin, 
print precision, print width, horizontal tabs, com- 
parison tolerance, and random link. In those days, 
those were global characteristics of a workspace, 
and there was no way to make them local to a 
function. Subsequently, IBM introduced the con- 
cept of system variables. System variables provided 
a way not only to ask about those aspects of the 
workspace, but also to specify them, and to make 
them local to a function. The first six elements of 
2 [WS 3 formerly reported the global values of 
O70, OPP, OPW, OAT, OCT and DRL, but at present 


contain the value 1. 


The remaining six elements have significance as 
follows: 


Element Contents 


Number of symbols the symbol table 
can accommodate 


Number of symbols entered in the 
symbol table 


Account number of the owner of the 
task (same as the first element of 
OAT) 


Number of the port to which the task 
is attached 


Task number 








Input/output translation, according to 
the following codes: 


o Not applicable (because the 
task is not a T-task) 
1 IBM correspondence encoding 
2 IBM BCD encoding 
TY33 (or 64-bit ASCII) en- 
coding 
Typewriter-pairing ASCII en- 
coding 
Bit-pairing ASCII encoding 


R<2 [WS 4 Workspace control information 
Result: A numeric vector of three elements. The 
vector describes the workspace in the same. way 
that [JIRDCI describes a file component. The three 
elements have significance as follows: 


1. Size of the workspace, in bytes (that is, gross 
size of the workspace minus [WA) 


2. Account number of the task which saved the 
workspace, or 0 in a workspace that has not been 


saved 


3. Timestamp showing the date and time at which 


f the workspace was saved (or 0 in a workspace 


that has not been saved) 


The time and date are encoded in a single element 
as the number of seconds since 0:00 hours on 1 
March 1960. Functions for encoding and decoding 
timestamps in that form may be found in the 
workspaces 1 FILEAID and 1 T5. 


R-3 (WS Y Members of group named in 


Y 


Right argument: A character array containing 
a single name. The name must be a well-formed 
name, but it doesn’t have to be the name of an 
object that actually exists. The array may be a 
vector or a 1-row matrix, or, if it’s a single- 
character name, a scalar. 
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Result: A character matrix containing the names 
of those objects (if any) that are members of a 
group having the name shown in the right argu- 
ment. The result contains a row for each such 
name, and as many columns as needed to accom- 
modate the longest name. Names are arranged 
left-justified, with trailing blanks if need be. The 
rows of the result are arranged in alphabetical 
order. 


If the visible meaning of the name contained in 
Y isn’t the name of a group, or if the group exists 
and is visible but has no members, the result is 
an empty matrix. 


Rey (WS Y Storage space for the objects 


named in Y 


Right argument: A character array containing 
any number of names. The names may be ar- 
ranged in a matrix, with exactly one name on each 
row, or they may appear as a vector with the 
successive names separated by blanks. If you use 
a matrix, each row may have any number of lead- 
ing or trailing blanks, but no row can be entirely 
blank. If there’s just one name consisting of one 
character, it may be a scalar. 


Each name must be a well-formed name—that is, 
a set of characters that could form a valid name. 
But it isn’t necessary that an object of that name 
actually exist in the workspace. 


Result: A numeric vector containing one element 
for each of the names contained in Y. 


The value of each element is the number of bytes 
that the object designated by the visible meaning 
of the corresponding name occupies in storage. 
This figure includes both the data itself and the 
data description (type, rank, shape, etc.) but not 
the object’s name. For a variable, this figure is 
identical to the amount of space you’d need in a 
file component in order to store it. 


When a name in the right argument Y is the name 
of a shared variable, the value reported is the 
value last visible in this workspace; using 4 [WS 
does not count as a use of the shared variable. 


R<e5 (WS Y Nameclass of objects named 
in Y at each level of the state 


indicator 


Right argument: A character array containing 
any number of names. The names may be ar- 
ranged in a matrix, with one name on each row, 
or you can supply them as a vector with the suc- 
cessive names separated by blanks. If you use a 
matrix, each row may have any number of leading 
or trailing blanks, but no row can be entirely 
blank. If there’s just one name consisting of one 
character, it may be a scalar. 


Each name must be a well-formed name—that is, 
a set of characters that could form a valid name. 
But it isn’t necessary that an object of that name 
actually exist in the workspace. 


Result: A numeric matrix, showing the use of 
each name at each level of the state indicator. 


The result has one row for each name identified 
in Y, and one more column than the number of 
levels in the state indicator. The first column of 
the result corresponds to the top row of the state 
indicator. The second column of the result corre- 
sponds to the second row of the state indicator, and 
so on. Finally, at the right end there’s an extra 
column to indicate each name’s global meaning— 
that is, the class of object the name refers to when 
no functions are being executed, and so the state 
indicator is empty. 


The values in an element in the result of 5 ws 
indicate the class of object a name refers to, ac- 
cording to the following code: 
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Meaning within a 
defined function (each 
column except the last) 


Not localized at this level 


Meaning outside 
any defined function 
(the last column) 


(Not possible) 


(refer to next column to the right) 


Localized at this 
level but not yet used 


Localized at this level, in use 


as the name of a function 


Localized at this level, in use 


as the name of a variable 


(Not possible) 


In use at this level as a label 


Notice that since the code 8 refers only to a local 
use of a name, it can never appear in the last 
column. Similarly, the value 1 can never appear 
in the last column. Since a group can only exist 
as a global object, the code 4, meaning “group,” 
can appear only in the last column. 


Comparison of WC Y and 5 [WS Y: These 
two functions provide similar information. The 
function 5 [WS Y reports the class of use made for 
each name at each level of the state indicator, 
whereas [INC Y reports only the class that de- 
scribes the visible use of the name. If you wanted 
to select (from the result of 5 DWS) just those 
entries that describe a visible use, you could do it 
by a sequence such as the following: 


QWS+5 OWS Y 
VISIBLE+( (+\QWS<0 )OQWS)[ 070] 


The two functions differ also in the number of 
classes they discriminate, and the codes they use 
to refer to those classes. The classes and the codes 
used to represent them can be compared as fol- 
lows: 





Not used 


Name of a function 


Name of a variable 


Name of a group 


(Not possible) 





Owe 5 [Ws 
( Describes (Describes 
the visible the meaning 
Class meaning ) at each level) 


Unlocalized = 


Function 


Variable 


Label 


Other 
(i.e. Group) 


Value of the variable named 
in Y 


Re6 (WS Y 


This function takes an argument containing the 
name of a variable (as a character array) and 
returns the value of that variable. Thus, when Y 
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contains the name of a variable, the expression 
6 DWS Y has the same effect as 4y. Indeed, 
6 [WS was introduced before a general execute 
facility existed. But note that the only thing that 
can appear in the argument of 6 [WS is one name. 
Moreover, that name must be the name of a varia- 
ble or a label. 


Right argument: A character array containing 
a single name. The name must be a well-formed 
name, and must be the name of a variable or label 
that is currently visible. The array may be a vector 
or a l-row matrix, or, if it’s a single-character 
name, a scalar. 


Result: The value of the variable or label named 
in Y. 


When the name in Y is the name of a shared 


variable, the result is the last value already visible 
in the workspace; using 6 [WS does not constitute 


a use of the shared variable. 
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Chapter 26: 


SYSTEM FUNCTION 
AND VARIABLES 
FOR 

EVENT TRAPPING 





OER Event report (system varia- 
ble) 


OER is a variable that the system sets, but which 
you may use in diagnosing an error or interrupt. 
(You could also set a value of DER, but it would 
be pointless to do so.) 


Following a reportable event, the system sets the 
visible value of DER. A reportable event is any of 
the events included in the list of events shown in 
Chapter 13, or an event generated by use of 
(SIGNAL. Note that an event that arises during 
use of a system command is never reported in 


OER. 


The value that the system gives to DER is normally 
a three-row character matrix. However, if there 
isn’t enough space in the workspace to accommo- 
date it, the system instead makes DER a 1-by-4 
character matrix containing only the event num- 
ber. A full three-row event report uses the rows 
as follows: 


1. A four-character representation of the event 
number, right-justified, with leading blanks, fol- 
lowed by one blank, followed by the event title (if 


any). 


2. Reproduction of the statement on which the 
system was working at the time the event occurred. 


When the statement was part of a defined func- 
tion, the row starts with the function’s name and 
the line-number in brackets. Following that, 
there’s one blank and then the line (or portion of 
a line) on which the system was working. Howev- 
er, if the function is a locked function, the body 
of the line is represented only by the symbol ¥. 


3. A caret indicating where (within the statement 
displayed in row 2) the system was working when 
the event occurred. 
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The total number of columns in [JER is sufficient 
to accommodate the longest row; the others are 
padded with blanks if necessary. 


Note that event 2001 (return to immediate execu- 
tion) does not set a new value for OER, even 
though it’s a trappable event. Note that events 
67 and 68 (forms of system error) do cause DER 
to be set, even though there’s no way to trap them. 
When a task is terminated abnormally 
(“bounced”), OER is set to show one of the inter- 
rupts. Even though interrupts ordinarily can be 
trapped, an interrupt forced by a “bounce” condi- 
tion can’t be trapped, but is recorded in DER. 


When the relevant trap definition in [TRAP con- 
tains action C (“cut back the state indicator”), the 
system first cuts back and then sets DER. The 
UER whose value is set is the one visible after the 
action but before the system executes the trap 
line. 


OTRAP Event trap (system variable) 


[TRAP is a variable that you set and the system 
uses. Whenever a trappable event occurs, the sys- 
tem searches the value of [TRAP for an applicable 
trap definition. The system starts by examining 
the visible value of DTRAP, but if it doesn’t find 
an applicable trap definition there, it continues in 
sequence through each of the shadowed values of 
UTRAP. The system’s behaviour with [TRAP is 
thus one of the few instances in which a shadowed 
value may be directly involved in execution. (If 
your shared-variable partner makes a change to a 
variable that for you is shadowed, you can detect 
that as a state change even though you can’t see 
what the change is; the class of use of a shadowed 
name can be reported by the function 5 DWS.) 


Well-formed DTRAP: As soon as you set a value 
for DTRAP, the system examines it to verify that 
it is well-formed. If it is well formed, the system 
leaves its value unchanged. But if DTRAP is not 
well formed, the system resets it by executing 
UPRAP+''. Since the system verifies whether 
OTRAP is well formed as soon as you set it, it is 
prudent to examine it immediately. If (TRAP still 
has the value you gave it, it is well formed. If the 
system has reset it to make it an empty vector, the 
value you assigned to it was not well formed. 


Watch out: An expression such as 
OK+0#x/p[TRAP+T 


does not constitute such a test. Its result would 
always depend on the shape of 7, regardless of 
whether the system did or did not reset the value 
of QTRAP. To verify that the system has accepted 
UTRAP, you need to use a test that is independent 
of your act of setting [ITRAP, for example: 


OTRAP+T © OK+0%x/p[]TRAP 


Form of DTRAP: A valid (TRAP consists of one 
or more trap definitions. TRAP must be either a 
matrix, containing one trap definition on each row, 
or a vector in which the first character is a delimi- 
ter, and each use of the delimiter is followed by 
a trap definition. A well-formed Q7RAP is one each 
of whose trap definitions is well formed. 


Form of a trap definition: A well-formed trap 
definition consists of 


1. List of event numbers: Each event number 
is formed solely from the characters 0-9, and suc- 
cessive event numbers are separated by blanks. 


2. An action code, which may be any one of 
C E N S or D, separated from the event numbers 
by a blank. Event number 2001 may be followed 
only by action D, and action D may be preceded 
only by event 2001. 


3. Following action Æ or C, and separated from it 
by a blank, there may be a trap line. The trap 
line is a line containing any number of statements 
(but not more than 500 characters). If an event 
occurs that is covered by the trap definition, the 
system executes the trap line in the same way that 
it would if you had keyed it from the terminal for 
direct execution. 


Following action D, there may appear one of the 
keywords EXIT or CLEAR. If one of them is used, 
it must be separated from the action code D by at 
least one blank. 
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Validity of the trap line is not checked: When 
the system accepts a value of [TRAP as well 
formed, it means only that [TRAP meets the fore- 
going criteria. The system makes no attempt to 
verify that it will be possible to execute the trap 
definition. 


OSIGNAL Y 
X DSIGNAL Y 


Signal event Y 
Signal event Y with message 
X 


Right argument: A numeric vector or scalar, 
whose first element (if any), must be a positive 
integer less than 1000. The right argument pro- 
vides the event number to be signalled. 


Left argument: The left argument, if used, pro- 
vides a title for the error to be signalled. It must 
be a character scalar or vector of less than 256 
elements. 


Effect: When the argument Y is empty, none. 


When the argument Y is not empty, the system 
aborts the activity at the top of the state indicator. 
That activity is the most recently invoked defined 
function, or use of ¢, or Q input. 


The system signals an error event to the function 
(or 2 or D) which invoked the activity thus 
aborted. The number of the event that is signalled 
is the first element of Y. 


Following the error signal, the system searches 
(TRAP for a trap definition covering its event 
number. If it finds a relevant trap definition, it 
acts upon it as described in the section on 
OTRAP . 


After aborting the function which used SIGNAL, 
the system sets the visible value of DER to an event 
report. The first four characters of the event report 
contain the character representation of the event 
number. The remainder of DER reproduces the dis- 
play described below (and also in the section on 
DER). 


If the system doesn’t find a trap definition for the 
signalled event, it halts execution and displays an 
error message. 


Content of (SIGNAL message: When [JSIGNAL 
is used dyadically, the first line of the error mes- 
sage is the title provided in the left argument of 
OSIGNAL. When OSIGNAL is used monadically 
and the event number is one for which the system 
has a recognized title, the first line of the error 
message is that title. But if the event number is 
one for which there is no recognized title, no title 
is displayed. 


Following the title (if any), the system displays 
the statement that invoked the function whose exe- 
cution was aborted. If that statement was part of 
a line within a defined function, the display starts 
with the function name and line number. To the 
right of the function name (if any), the system 
displays the statement that invoked the aborted 
function, or the symbol ¥ if the function was 
locked. On the next line it displays a caret point- 
ing to the aborted statement. 


Error signalled during immediate execution: 
Using OSIGNAL from the keyboard during imme- 
diate execution has the same effect as using it 
within a defined function. That is, it aborts execu- 
tion of the function at the top of the state indica- 
tor. If you use OSIGNAL in immediate execution 
when there’s nothing on the state indicator, the 
system displays your entry with a caret pointing 
to your use of DSIGNAL. 


Result: None. 


dey 
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Chapter 27: 


SYSTEM FUNCTIONS 
FOR TERMINAL 
INPUT/OUTPUT 





Most of the time, input from a terminal or display 
to a terminal doesn’t require any explicit instruc- 
tions at all. While it’s in execution mode, the sys- 
tem assumes automatically that, following each ex- 
ecution, it will return to the terminal for further 
instructions; unless you direct it otherwise, it auto- 
matically displays the results of any calculations 
you request. The system does all that without ex- 
plicit instructions. 


The rules governing alternative modes of input are 
discussed in the chapter entitled “Modes of Inter- 
action at a Terminal.” The rules governing auto- 
matic displays are discussed in the sections headed 
“When the Result is Displayed” and “System- 
default Displays.” This section concerns explicit 
control of input and output. 


Transmission to and from terminals is handled by 
using the symbols [Q and M, and by three system 
functions, JOUT, DARBIN, and DARBOUT. The sym- 
bols ( and [ have dual uses, covering both input 
and output at a terminal. The system function 
OUT permits you to have data that would other- 
wise be displayed at your terminal appended to a 
file. The functions DARBOUT and DARBIN permit 
you to send and receive arbitrary characters, in- 
cluding special control characters that are outside 
the normal scope of APL, or entries that would 
not otherwise be acceptable as APL characters, 


A note about the syntax of [] and M: The sym- 
bols 0 and [f were introduced into APL early dur- 
ing the development of the language. It isn’t really 
clear just what syntactic category they belong to. 
Both [] and [| can be used to solicit input from the 
terminal. In that regard, they resemble the func- 
tion DARBIN, which also accepts input from the 
terminal and delivers it to the active workspace. 


But [ and M can also be used to the left of an 
assignment arrow, in a phrase such as Mex. In that 
context, [] or [ behaves more like a variable than 
a function. 


SYSTEM FUNCTIONS FOR TERMINAL INPUT/OUTPUT 234 





Some years after the introduction of 0 and M, IBM 
introduced the concept of “shared variables” and 
(after the event) it seemed one might argue that 
O and [M are variables automatically and perma- 
nently shared with the terminal. Be that as it may, 
there’s no doubt about what they do. Their 
behaviour during input and output is described 
here. See also the chapter entitled “Modes of In- 
teraction at a Terminal.” 


RokY Quad output 


Argument (that is, what you can put to the right 
of De): Any data object. 


Effect: The object is displayed according to the 
system’s default rules governing display. Those 
rules are described in the section headed “System- 
default Displays.” A default display is affected by 
the visible value of the system variables DPW (print 
width) and DPP (print precision). 


The effect of the expression 
Bae 4 
is identical to the expression 


Y 


When the object being displayed is a package, the 
display consists solely of the message 
xxPACKAGE*x. 


A display produced by [0 is treated as a separate 
display. That is, before starting on the display, the 
system first displays any [ output that is pending. 
(See the discussion of M.) 


If the object you’re displaying is organized into 
columns (that is, if it’s an array having rank 2 or 
greater) and the preceding use of [M left the cursor 
somewhere other than at the left margin, the sys- 
tem moves the cursor to the beginning of the next 
line before it starts the D display. But it does that 
only when both those conditions apply. 


At the end of a O display, the system always re- 
turns the cursor to the left margin of the next line. 
Automatic repositioning of the cursor following 
display is what distinguishes [0 output from [ out- 
put. 


Result: The result of DeY is the value of Y, un- 
changed. The result may be used by any function 
further to the left. For example, the expression 


Rey 


causes display of Y, and assigns the value of Y 
to R. By inserting Qe} at various points within a 
compound expression, you can get displays of the 
partial results. 


Re\Y Quote-quad output of Y 


Argument (that is, what you can put to the right 
of Me): Any data object. 


Effect: The object is displayed according to the 
system’s default rules governing display. The dis- 
play is not automatically followed by a carriage 
return. For that reason, a sequence of several in- 
stances of [] output may appear across a single line 
at the terminal. 


The display produced by each use of I output is 
identical in appearance to that produced by 0 out- 
put, or to default displays. A package produces the 
display **PACKAGE**. The appearance of a 
numeric array is affected by QPP (print precision ). 


If the object you’re displaying is organized into 
columns (that is, if it’s an array having rank 2 or 
greater) and the cursor has been displaced from 
the left margin by a preceding use of [J output, the 
system first returns the cursor to the first position 
on the next line. In that respect, [1 output behaves 
in the same way as [] output. 


Following M output, the system leaves the cursor 
position unchanged. That’s where the cursor will 
start from if you go on to request further output 
with [M or DARBOUT; that’s where the cursor will 
be if you now request input with either [J or 


DARBIN. 
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(However, if the next thing you do is return to 
immediate execution mode, or switch to D input, 
the system moves the cursor to position 7 of the 
next line before awaiting new input.) 


The overall width and the timing of M displays: 
The system variable DPW (print width) affects dis- 
plays generated by M, but not in the same way that 
it affects [] output or system-default output. With 
E output, the effect of OPW is not specific to each 
use of [, but is cumulative over a sequence of uses 
of [] output. 


When you request a display with [ output, the 
system doesn’t necessarily transmit it at once to the 
terminal. If the thing being displayed is a scalar 
or a vector (that is, something that doesn’t auto- 
matically require several lines), and if the number 
of characters needed to display it doesn’t exceed 
OPW, the system waits to see what you’re going to 
do next before it transmits the last line of the 
display. Because the system doesn’t reposition the 
cursor at the end of each [ output, there might be 
another [ output, and that next one (if it exists ) 
might require a display starting just to the right 
of the preceding display. Characters generated by 
several different displays may thus appear on the 
same line, and are transmitted together. 


While it’s preparing [M output, the system accumu- 
lates the needed characters in an area of internal 
storage known as the [] output buffer. The system 
prepares the display line by line in the [ ouput 
buffer. The system transmits the current contents 
of the buffer to your terminal whenever either of 
the following two things occurs (whichever hap- 
pens first): 


1. The line now being prepared is complete and 
there’s another line after this one. 


A line could be complete either because the object 
being displayed is organized into rows (because 
it’s an array having rank 2 or greater), or because 
the data contain a carriage-return character. 


2. The number of characters in the buffer has 
reached []PW, but the system hasn’t yet reached the 
end of the row of data. 


As soon as either of those happens, the system 
transmits the contents of the buffer. The M output 
buffer is then empty. 


If the buffer was transmitted because it had grown 
to PW characters and the system still hadn’t en- 
countered a line-end or a carriage return, then the 
line next to be transmitted is a continuation line. 
When the next line of display is a continuation, 
the system starts its new accumulation by putting 
blanks into the buffer’s first six positions. That 
way, the continuation (when transmitted) will ap- 
pear indented. Then the system resumes the 
process of accumulating characters in the ("| output 
buffer. 


The last line of [ output: The characters that 
are destined to be the last line of a [ display (or 
of a sequence of [] displays) are not immediately 
transmitted. The system leaves them there in the 
buffer until one of the following things happens: 


1. You’re ready to return to immediate execution 
mode. That might be because the function you’ve 
been executing is about to reach a normal end, or 
because it has been interrupted by an error or an 
interrupt signal. 


2. You’re ready to start a display produced by 
anything other than [. That includes a display 
produced by DARBOUT, DARBIN, or by D, or any 
system-default display. 


3. Youre ready to request input via D, M, or 
y q P 


DARBIN. 


When the last line of [{ output is transmitted be- 
cause you’re about to ask for [ input, the charac- 
ters in that last line of output are also included 
as part of the input. This matter is discussed fur- 
ther in the section on [ input. 


Result: The result of [eY is the value of Y, un- 
changed. The result may be used in any function 
further to the left. 
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Rey] Character input 

When the symbol () appears without + to the right 
of it, it behaves rather as a niladic function might. 
It causes the system to accept from the keyboard 
one line of character data. 


An important property of [Ħ input is that you can 
combine it with [| output. When you do that, you 
can display a prompting message and then accept 
a reply on the same line. 


Argument: None. It isn’t clear whether [M should 
be regarded as a system variable or a function, but 
if it’s a function, it’s a niladic function. 


Effect: The cursor remains wherever it hap- 
pened to be, and the system turns the keyboard 
over to you to accept one line of input. 


If there was no preceding display, or if the preced- 
ing display was produced by O or by sys- 
tem-default output, then the cursor is at the left 
margin. It remains there. 


But when the preceding output was produced by 
M output or by JARBIN or DARBOUT, those displays 
are not automatically followed by a carriage re- 
turn. When the system turns the terminal over to 
you for your entry, the cursor remains right where 
it was at the end of that display. That is, it waits 
at the next position to the right of the last charac- 
ter of the preceding display. 


You can make one line of entry. Your entry con- 
tinues until you press RETURN. However, the 
number of characters you can enter is restricted 
by the size of the input buffers that the system 
uses to process what you enter. At present, that 
buffer has room for 521 characters. If you type 
more than that before pressing RETURN, the 
system rejects your entry with the message CHAR 
ERROR, and awaits a new entry to supply a value 


for M. 


Interrupting [| entry: If your entry contains the 
sequence of five keystrokes O BACKSPACE U 
BACKSPACE T, execution of the statement con- 
taining [] is halted with the message INTERRUPT. 
You can resume execution from the beginning of 
that line by entering +JZC. 


ee 


Watch out: Because RA input may also require 
an accompanying display generated by MY, you 
don’t want to execute RHY without [-Y. Following 
an interrupt, if execution is resumed, it must be 
resumed from the beginning of the line. It is 
therefore prudent always to arrange such a pair 
of statements so that they fall on the same line; 
for example: 


MY © Ret 


Result: A character array containing the con- 
tents of the [-output buffer overstruck with the 
entry supplied from the keyboard. 


If the -output buffer was empty, and the entry 
you supply from the keyboard is a single charac- 
ter, the result is a character scalar. Otherwise, the 
result is a character vector. 


How [ output is combined with [ input: The 
request for [ input causes the system first to dis- 
play the characters remaining in the [l-output 
buffer. (Rules governing that are described in the 
section on [1] ouput.) The system then awaits input 
with the cursor positioned just to the right of the 
display, on the same line. If you enter characters 
starting at that position, the result consists of the 
characters that were displayed on that line, fol- 
lowed by the characters you entered in response. 


But if during your entry you backspace so as to 
reposition the cursor over the characters already 
displayed, the system combines the characters you 
enter now with the characters already there, to 
form overstrikes, just as it would if you had your- 
self entered all the characters on that line. For 
example, when the system displays [J and you 
backspace to it and overstrike it with +, the result 
contains the character B. 


If after backspacing you form an illegal overstrike, 
the system rejects the entry with the message 
CHAR ERROR. It displays the entire line (both the 
display and your entry) up to the point of the 
illegal overstrike, and awaits a corrected entry. 


Watch out: If after the statement requesting M 
output but before the statement soliciting A input, 
your program makes use of [ARBIN or 
DARBOUT, the system discards the contents of the 
[M output buffer. In that case, your entry is not 
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merged with the display. The result consists of all 
those characters running from the leftmost to the 
rightmost character you entered. That’s true even 
if you backspaced leftward of the original cursor 
position. 


Separating the prompt from the reply: In 
many applications, the program needs first to dis- 
play a prompting message, to indicate what infor- 
mation it wants you to enter. Then it collects your 
response. The program may contain a sequence 
such as this: 


PROMPT+'NAME? ' 
[PROMPT © RA 


If in response to the prompt W IME? you don’t use 
the BACKSPACE key, but simply enter your 
reply (for example, the characters ABIGAIL 
MADISON), then the value of NAME will be the 21 
characters NAME? ABIGAIL MADISON. 


There are various ways the program might sepa- 
rate the response from the prompt. It is imprudent 
for the program simply to discard the first ele- 
ments of the result, since you might have back- 
spaced into the area of the prompt. That could 
easily happen if the final characters of the prompt 
are blanks. It might be better to look for the first 
point at which the result differs from the last line 
of the prompt, for example 


LASTLINE*«($A\PROMPT2CR) / PROMPT 


Re(V\R#(pR)pLASTLINE, (pR)p1tO4AV)/R 


An alternative approach which is not recom- 
mended is to deliberately empty the [ buffer, by 
a sequence such as this: 


(+PROMT © DARBOUT '' © Ref 


This has the major drawback that it loses visual 
fidelity. Following the use of DARBOUT, the system 
interprets your entry as if the cursor were at the 
left margin, and therefore disregards any uses you 
make of the BACKSPACE key which (as far as 
the system can tell) were transmitted while the 
cursor was at the margin. If you were to use such 
a scheme, and were to overstrike characters in the 
prompt, the system would be unable to detect that. 
Moreover, if your entry backspaces to the left of 


the initial cursor position, the system disregards 
them but not characters other than backspace. 
Thus, the system may fail to perceive as over- 
strikes characters that, to you, appear to be on top 
of each other, or may perceive as overstrikes char- 
acters that, to you, appear distinct. 


RQ Evaluated input 


When the symbol [ appears without < to the right 
of it, it behaves rather as a niladic function might. 
It causes the system to accept from the keyboard 
one line for immediate execution, to execute. that 
line, and to take its result as the result of the 
function. Control then returns to the statement 
that contained the [] symbol. 


Argument: None. It isn’t clear whether D should 
be regarded as a system variable or as a function, 
but if it’s a function, it’s a niladic function. 


Effect: The system displays the symbols Q: at 
the left margin, and then turns the keyboard over 
to you with the cursor at position 7 of the line 
below. 


You may now enter one line of APL. 


Each name occurring in the line you enter refers 
to its visible meaning. That is, the interpretation 
of a name is subject to localization by the functions 
that are currently active. 


Result: The data resulting from execution of the 
line you entered. If your line contained several 
statements separated by diamonds, the result is the 
result of the last statement. 


Effect of a non-responsive entry: If in re- 
sponse to the system’s prompt of []: you simply 
press RETURN, the system reissues the prompt 
and again awaits a line of entry. 


If your response is an invalid expression, the sys- 
tem reports the error and reissues the prompt and 
again awaits a line of entry. 


If your response is a valid statement, but one that 
produces no result, the system accepts the entry, 
but then reports a VALUE ERROR in a statement 
that requires the result of D. 
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While you’re responding to a request for J input, 
you can’t use an entry beginning with > to force 
a branch in the function that contained the 0. For 
one thing, a branch statement does not return a 
result. 


However, you can use + alone (the so-called naked 
branch) to abort execution of the immedi- 
ate-execution entry that led to this use of (1. 


If your response to the system’s prompt [: is 
something that would, in a different context, be a 
valid branch statement (for example, +6 or 
+LABEL, etc.), the system rejects your entry with 
the message SYNTAX ERROR, and reissues the 
prompt []:. However, the system treats >0 or 
+10 within O in the same way as '>0' or 
'+10' within the argument of ¢, and returns the 
values 0 or 10, respectively. 


If, in response to the system’s prompt, you enter 
a system command, the system executes the com- 
mand. Then the system reissues the prompt and 
again awaits a line of entry. Of course, if the 
command destroyed the former contents of the ac- 
tive workspace, as would happen if you replied 
)CLEAR or )LOAD, the request for O input is de- 
stroyed with it. If you enter > or )RESET that, too, 
aborts the request for input. 


If you enter the command )COPY or )PCOPY, the 
system carries out the command (and, if it is suc- 
cessful, copies into the workspace the objects 
you’ve requested) and then reissues the prompt 
and again awaits a line of entry. That is, an object 
thus copied is not accepted as the response to 
O:. Moreover, note that the copy commands 
apply to global objects, whereas the response to 0 
applies to the visible use of names. 


If in response to the system’s prompt []: you enter 
a )SAVE command, the system carries out the com- 
mand (provided it’s valid) and then reissues the 
prompt. When you subsequently load the work- 
space thus saved, you will find execution sus- 
pended on the line that contained the O symbol. 
You can resume execution at the beginning of that 
line by >{JZC. But the request for 0 input won’t 
be reissued until you do. 


DARBOUT Y 
R4 JARBIN Y 


Arbitrary output Y 
Arbitrary input following 
output Y 


These functions permit you to transmit to your 
terminal, any of the possible transmission codes 
(regardless of what they mean within the APL 
system, or even whether they mean anything to 
APL), and to receive back a record of whatever 
is next transmitted from your terminal. 


Each of these functions causes the system to trans- 
mit to the terminal a pattern of bits. You could 
think of each segment of that pattern as a charac- 
ter. Each character that’s transmitted is derived 
from the binary representation of the numbers in 
the argument of [ARBOUT. For example, 
QARBOUT 7 causes the system to transmit a signal 
formed from the binary representation of 7. What 
the terminal will do when it receives that signal 
depends on the encoding system used by the type 
of terminal you’re using. 


Each use of [ARBOUT or QARBIN causes a trans- 
mission from the system to the terminal. DARBIN 
then accepts a reply from the terminal, and en- 
codes it in the same way. 


Each transmitted character consists of eight bits 
when you’re communicating with an ASCII termi- 
nal, and seven bits when you're communicating 
with an IBM terminal. 


Argument of DARBOUT or QARBIN: A scalar or 
vector. The argument may be either character or 
numeric. 


When the argument is numeric, each element must 
be an integer in the range 0 through 511 (when 
transmitting to an ASCII terminal), or 0 through 
127 (when transmitting to an IBM-encoded termi- 
nal). 


When the argument is composed of characters, 
each character must be a member of 128+tDAV. 
The effect is equivalent to a numeric argument 
formed by 


(OAV iY) -UI0 
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Reference vector to construct character 
prompts: It’s likely that the prompt you wish to 
transmit to the terminal will consist largely or 
even exclusively of conventional characters. To 
help you find the arbout codes that correspond to 
standard characters, the workspace 1 ARBOUT 
contains four 128-element character vectors, called 
ARBTYPE, ARBBIT, ARBCORR, and ARBBCD, to be 
used respectively with typewriter-paired ASCII 
terminals, bit-paired ASCII terminals, IBM corre- 
spondence terminals, and IBM BCD terminals. 
Suppose you need to transmit the prompt 
"HELLO ' to an ASCII typewriter-paired termi- 
nal. You can do that (with OI0+«0) by the follow- 


ing: 


OARBOUT ARBTYPE:'HELLO ' 


Watch out: In general, an expression such as 
OARBOUT 'HELLO' 


does not cause the terminal to display HELLO. 


Output effect of DARBOUT or DARBIN: Before 
anything else happens, the characters remaining in 
the M output buffer (if any) are transmitted to the 
terminal, and the buffer is emptied. (This means 
that H input, following use of QARBOUT or 
QARBIN, will not produce a result that is merged 
with the characters of the last line of the M out- 


put.) 


The system transmits to the terminal the signals 
indicated by the argument Y. This may result in 
visible characters, or in various other actions at the 
terminal. 


Effect on the cursor: During output other than 
arbitrary output, the system keeps track of the 
position of the cursor so that it can: 


1. Decide when output has reached the width 
specified in (JPW. 


2. Calculate when to use tab characters to speed 
up display. 


3. Calculate how many idles may be required to 
reposition the cursor at the next line. 


It’s important to note that output produced by 
OARBOUT or (JARBIN ignores and may confuse 
all three of those. If you use JARBOUT in a way 
that displaces the cursor, and follow it by conven- 
tional output (that is, output produced by D or 
B, or default output), the system’s calculation of 
tabs, or its folding of long lines in response to 
OPW, or its insertion of idles following RETURN, 
is likely to be wrong. 


Input effect of [ARBIN: Following the trans- 
mission specified by the argument, the system 
awaits one transmission from the terminal. This 
transmission consists of each character sent from 
the terminal up to and including your first use 
of RETURN from an ASCII terminal or of EOT 
at an IBM-encoded terminal. (On IBM terminals 
used with APL, EOT is usually sent automatically 
following each use of RETURN.) 





Note that if you press BREAK at an ASCII ter- 
minal, the effect may vary, depending both on the 
particular terminal and whether or not it is con- 
nected through the network. BREAK may be com- 
pletely ignored, or may cause the system to reissue 
the prompt and again await input. Through the 
Sharp network, BREAK during DARBIN input 
may be used as 0 (or possibly a succession of 0’s). 
From an IBM terminal, pressing ATTN during 
input produces 93 in the result. 


Result of QDARBOUT: None. Since [ARBOUT 
produces no result, it may be used only as the root 
function of the statement in which it appears. 


Result of QARBIN: A numeric vector represent- 
ing the transmission received from the terminal. 
The result includes the character which marks the 
end of transmission. Thus, the result of DARBIN 
from an ASCII terminal ends in 13 (CR), and 
from an IBM terminal ends in 45 15 (CR, 
EOT). 


Watch out: You might think that instead of 
using an expression such as 


X+(JARBIN PROMPT 
you could equally well use a sequence such as 


[QARBOUT PROMPT © X4JARBIN 10 


SYSTEM FUNCTIONS FOR TERMINAL INPUT/OUTPUT 240 





But in practice, the 2-step use of DARBOUT fol- 
lowed by DARBIN 10 is subject to a problem that 
can be avoided if you stick to the more general 
form X<{JARBIN PROMPT. 


The trouble arises when the first use of 
DARBOUT must include the signal that makes the 
terminal ready to transmit (for example, the Cir- 
cle-C which should be the last character of the 
prompt sent to an IBM 2741 terminal). When it 
receives that signal, the terminal may appear 
ready to transmit before the system is ready to 
receive what you send. If that happens, the first 
part of the response from your terminal may be 
lost. 


This problem doesn’t arise when a single use of 
CARBIN both sends the prompt and collects the 
response. 


ROUT Y Append output to file Y 
Argument: A 2-element integer vector, or an 
empty vector. 


When the argument contains two elements, the 
first element indicates whether or not display is to 
be sent to the terminal. Its value must be either 
1 or 0. 1 means that henceforth, output is sent to 
the terminal, while 0 means that henceforth, out- 
put is not sent to the terminal. 


The second element of the argument of DOUT will 
be interpreted as the tie number of a file whenever 
output is generated. It must be either 0 (no file 
for output), or a positive integer (that is, a num- 
ber that could be a tie number). But at the mo- 
ment you invoke DOUT, it isn’t necessary that the 
second element be the number of a currently tied 
file (unless you use (OUT in such a way that it 
produces output). 


Result: A 2-element vector indicating the former 
value of the DOUT parameter for this task. When 
there hasn’t been any explicit use of DOUT during 
a task, the result is 1 0 (meaning that output goes 
to the terminal and not to a file). 


Note that DOUT 10 is a way of finding out the 
present state of the QOUT parameters without al- 
tering them. 


Effect; When the first element is 1, output is 
transmitted to the terminal. 


When the first element is 0, output is not trans- 
mitted to the terminal. 


When the second element is 0, output is not ap- 
pended to a file. 


When the second element is a valid tie number, 


output is appended to that file. 
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Chapter 28: 


SYSTEM FUNCTIONS 
FOR LOADING 


A WORKSPACE 





There are two functions which cause the system 
to load a saved workspace into the active area. The 
workspace you load replaces the entire contents of 
your active workspace (except for session varia- 
bles). The control of execution passes to the latent 
expression of the workspace that is loaded. 


If you need to pass information from the former 
active workspace to the new one, it must be by 
some means that survives the act of loading the 
new workspace. You might use the session variable 
LISP, or you might store the needed information in 
a file. If you put the information in a file, the new 
workspace will still need some way of knowing 
what file that is. You could identify the file either 
by adopting in advance a convention regarding the 
file you use for that purpose, or by passing that 
information in QSP. 


DLOAD Y Load workspace named in Y 
OQLOAD Y Quiet-load workspace named 
in Y 


Argument: A character vector or scalar contain- 
ing the name of a workspace. 


The argument consists of three fields, two of 
which may be empty. 


The first indicates the number of the library from 
which the workspace is to be loaded. When the 
library is your own, you may omit this field. 


The second field is the name of the workspace. If 
you include the library number, you must separate 
the name from it by at least one blank. 


If the workspace you’re loading is locked, you 
must include a third field containing its password. 
If you include a password, you must separate it 
from the workspace name by a colon. 
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The argument may include any number of blanks, 
provided that no blanks separate the digits of an 
account number, the characters of the workspace 
name, or the characters of the password. 


Effect: The indicated workspace is loaded. The 
system executes its latent expression DEX in the 
usual way. 


Following a successful [ZOAD (but not following 
OQ@LOAD), the system displays the time and date 
at which the workspace was saved, in the same 
way that it does after the system command 
)LOAD. That is the only difference between 
OZOAD and (]QLOAD. 


Result: Whether DLOAD or QQLOAD returns a re- 
sult is a moot question. The system’s syntax analy- 
zer accepts an expression in the form 
R+{]LOAD Y. However, executing the function 
causes either a successful loading of the indicated 
workspace or an error message. Either way, you 


never get to see the result. 
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Chapter 29: 


SYSTEM FUNCTIONS 
TO MANIPULATE 
PACK AGES 





A package serves primarily as a way of storing or 
transmitting a number of separate objects. In par- 
ticular, it gives you a way to store, within a single 
object, a collection that includes both functions and 
variables, and both numeric arrays and character 
arrays. 


A package is a single data object which contains 
within it a set of names. Accompanying each 
name, there may or may not be an object to which 
the name refers. Each name within a package may 
refer to: 


1. A variable (including another package) 
2. A function 


3. Nothing (that is, it may be a valid name that 
doesn’t refer to anything). 


From the outside, a package resembles a scalar. 
(Perhaps in some future extension of SHARP 
APL, it will be possible to form an array one or 
more of whose elements is a scalar that is also a 
package. ) 


A package contains within it any number of 
names. The names within a package must be dis- 
tinct from each other. However, they don’t need 
to be distinct from names used outside the package 
(or even from the name of the package itself). 


You can make use of the names within a package 
(and the objects to which they refer) only after 
you’ve extracted them from the package. There are 
relatively few things you can do with a package 
as a single object, and they are all involved with 
describing it, or with storing or manipulating it. 
You can: 


1. Make a package a variable by assigning a name 
to it 


2. Store or retrieve a package in a file 
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3. Pass a package as the argument of a defined 
function 


4. Return a package as the result of a defined 
function 


5. Copy one or more packages that have been 
stored as variables from one workspace to another 
(subject to the restriction that )COPY only applies 
to global objects). 


Since a package is a variable, its name appears in 
the display returned by the system command 
)VARS, or the result of DNL or 1 WS. A package’s 
nameclass is reported as “variable” by the function 
ONC or 5 DWS. The number of bytes required to 
store it is reported by 4 [WS. A package can be 
expunged with DEX or 6 DFD, or (provided it’s a 
global object), with the command )ERASE. 


A package is outside the domain of any of the 
arithmetic functions (such as + x - + etc.), the 
relational functions (such as =, > etc.), and of the 
structural functions (such as p > Qetc.). A pack- 
age has no array structure, and hence is outside 
the domain of 1 or [ J. 


A package cannot be an element of another array, 
and hence cannot be catenated to anything else. 
Nor can it be inserted into an array by using 
indexed assignment. (However, a package may be 
a member of another package.) 


You can’t directly display the contents of a pack- 
age. If X is the name of a package, the expression 


X 
produces simply the display 


xxPACKAGE* x 


You can distinguish a variable that is a package 
from a variable that is not a package by the rank 
of the result of the function QPVAMES. Applied to 
a variable Y, OPNAMES Y returns a matrix when 
Y is a package, and an empty vector when Y is a 
rectangular array. 


Namelists: Many of the functions for work with 
packages take as argument a character array of 
names. When a function requires a namelist, you 
can represent the names either as a vector in 
which the successive names are separated by 
blanks, or as a matrix. If you use a matrix, there 
must be one name on each row. Each name may 
have any number of leading or trailing blanks, but 
no row may be entirely blank. If there’s just one 
name, it may be either a vector or a 1-row matrix, 
or (if it consists of only one letter), a scalar. 


When the system produces a namelist, it always 
returns a matrix, with one name on each row. 
There’s a row for each name, and as many col- 
umns as are needed to accommodate the longest 
name. A shorter name is left-justified, and its row 
is filled out with blanks. 


RPACK Y Pack names in Y 

Argument: A namelist containing the names you 
want included in the resulting package. (See the 
discussion of namelists earlier in this chapter.) 


Each name must be a well-formed name. A name 
doesn’t have to refer to any visible object. If a 
name does refer to a visible object, it must be an 
object that can be included in the package; that is, 
its visible meaning may not be the name of a 
group. If the visible use of a name is as a label, 
the label will be included in the package, but as 
an ordinary variable rather than as a label. 


If you include the same name more than once in 
the right argument Y, the extra occurrences of the 
name have no effect. 


Result: A package. The package contains each 
of the distinct names included in the argument, 
together with the object to which that name refers, 
if any. 


When a name in Y is the name of a shared varia- 
ble, the value that is included in the package is 
the last value already visible in the workspace; use 
of monadic [PACK does not constitute a use of the 
shared variable. 
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Watch out: If you misspell a name in the argu- 
ment in such a way that it now refers to nothing 
visible: 


1. The object you intended will be missing from 
the package. 


2. You won’t receive an error message (since it’s 
permissible to include a name that has no refer- 
ent). 


3. If you subsequently use QPDEF to “unpack” 
this package, and do it in a context where the 
misspelled name refers to a visible object, that visi- 
ble object will be expunged. 


R-X (PACK Y Pack value Y with the name 


contained in X 


Right argument: Any data object. That is, a 
rectangular array or a package, but not a function. 


Left argument: A character vector (or a scalar 
or a l-row matrix) containing a single well- 
formed name. 


Result: A package containing the name shown 
in the left argument, and as its referent, the data 
in the right argument. 


R-X [PINS Y Insert package Y into package 
X 


Arguments: Each argument must be a package. 


Result: A package containing all the names and 
their referents from package Y, and also those 
names that occur in X but not in Y, together with 
the objects they refer to in package X. 


In other words, the resulting package contains the 
union of the sets of the names in the separate 
packages, but wherever a name in Y is the same 
as a name in X, that name’s referent from Y is the 
referent included in the result. 


Watch out: The order in which the names in a 
package are reported is arbitrary. Moreover, the 


package resulting from QPINS does not necessarily 
have names in the same order as they appear in 
X. 


RAJPNAMES Y Names in package Y 
Argument: Any data object; that is, a rectangu- 
lar array or a package. 


Result: When the argument is a not a package, 
the result is an empty vector. 


When the argument is a package, the result is a 
matrix containing the names contained in the 
package. The matrix has one row for each distinct 
name, and as many columns as needed to accom- 
modate the longest name. Names are left-justified, 
and padded with blanks. 


Watch out: The order in which the system re- 
ports the names within a package is arbitrary and 
may be changed. 


ReX DPNC Y Nameclass in package Y of 
names in X 
R- DPNC Y Nameclass of each of the 


names in package Y 
Right argument: A package. 


Left argument: When the function is used 
dyadically, the left argument is a namelist. 


A name included in the left argument need not be 
a name actually present in the package; in fact, 
DPNC doesn’t even require that each name be well 
formed. 


Result: An integer vector indicating the name- 
class of names in the package Y. 


When the function DPNC is used with a left argu- 
ment, the result contains one element for each 
name in the left argument X. 


When the function is used monadically, the result 
contains one element for each distinct name in- 
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~ 


cluded within Y, in the same order as the names 
would be reported by OPNAMES Y. This leads to 
the identity 


ODPNC Y 4> (DPNAMES Y) OPNC Y 
An element of the result indicates the class of ob- 


ject to which the name refers according to the 
following encoding: 


“1 Name used with no referent 
o Name not present in the package 


2 Name refers to a variable 


3 Name refers to a function 





4 Not a well-formed name 


The encoding in the result of DPNC is based on the 
encoding used in the result of ONC. Since a pack- 
age can’t contain a label, the value 1 cannot ap- 
pear in the result of OPC. The value 1, meaning 
“name without referent” does not occur in the 
result of DNC. 


ReX OPVAL Y Value in package Y of the 


variable named in X 
Right argument: A package. 
Left argument: A character vector or scalar, or 
a 1-row matrix. The left argument must contain 
one name, and its referent in Y must be a variable. 


When X fails to meet those criteria, the system 


rejects your use of OPVAL with the message 
DOMAIN EEROR. 


Result: The value of the variable named in X. 
X OPDEF Y Define from package Y the 
names mentioned in X 
OPDEF Y Define all names from pack- 
age Y 
Right argument: A package. 


Left argument: When you use DPDEF with two 
arguments, the left argument X is a namelist. (See 
the discussion of namelists earlier in this chapter. ) 


Each name in X must meet all of the following 
criteria: 


1. It must be a well-formed name. 


2. It must be a name that is contained in package 
F. 


3. It must not be a name whose visible referent 
in the workspace is an active function. That is, its 
referent may not be a function that appears any- 
where on the state indicator. 


© 


$ 4. In a sealed workspace, its visible referent must 
not be a function that is locked. 


When any of the names in X violates any of those 
criteria, the system rejects your use of DPDEF with 
the message DOMAIN ERROR. 


Effect: Each name in X (when [JPDEF is used 
with two arguments) or every name in the pack- 
age (when (JPDEF is used with one argument) is 
defined in the workspace with the referent that it 
has in the package. The former visible referent of 
each of those names (if any) is erased, and is 
replaced by the referent from the package. (Note 
that when a name exists in the package without 
a referent, using DPDEF to bring that name into 
the workspace has the effect of expunging it.) 


Result: None. Because the function [PDEF re- 
turns no result, it must appear as the root function 
of the statement in which it is used. 


Protective definition of 
names in X from package Y 
Protective definition of all 
names from package Y 


R-X OPPDEF Y 


R- [QPPDEF Y 


Protective definition assigns a new meaning to a 
name only when the name has no visible use. It 
never expunges or alters the referent of an existing 
name. (In that way it is similar to the system 
command )PCOPY, except that )PCOPY, like most 
commands, refers to the global rather than to the 
visible meaning of each name.) 
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Right argument: A _ package. 


Left argument: When you use [PPDEF with 
two arguments, the left argument X is a namelist 
indicating which names you want to have defined. 
(See the discussion of namelists earlier in this 
chapter. ) 


Each name mentioned in X must be a name that 
is actually included in package Y. 


Effect: Each name in X (when QPPDEF is used 
with two arguments), or each name present in the 
package (when Q)PPDEF is used with one argu- 
ment) and which has no visible referent in the 
workspace, is given the meaning that it has in the 
package. 


Result: A character matrix. The matrix contains 
each of the names that appeared in the left argu- 
ment X (when OPPDEF is used with two argu- 
ments) or which is contained in the package 
(when DPPDEF is used with one argument) which 
was not defined because it had an existing visible 
use in the active workspace. 


R-X DPSEL Y Select names in X from pack- 
age Y 

R-X DPEX Y Expunge names in X from 
package Y 


These two functions are complementary. Each 
forms a package whose set of names is a subset 
of the names contained in the right argument. 
Each takes a namelist as its left argument. For 
OPSEL, the left argument specifies the names you 
want included, whereas for DPEX, it specifies the 
names you want excluded. 


Right argument: A package. 


Left argument: A namelist. Each name must be 
well formed. For QPSEL but not for OPEX, each 
name must be a name actually present in the pack- 
age Y. 


Result: A package containing a subset of the 
names included in package Y. 


The result of DPSEL contains each of the distinct 
names appearing in X, together with the referent 
that each of them has in package Y. 


The result of PEX contains each of the names 
present in the package Y but not mentioned in the 
namelist X, together with the referent that each of 
those names has in package Y. 


R-X [PLOCK Y Lock functions from package 
Y that are named in X 


Re [PLOCK Y Lock all functions from pack- 
age Y 


Each of these functions returns as its result a 
package containing the same names, with the same 
referents. However, those objects which in Y are 
unlocked functions become locked functions in the 
result. 


Right argument: A package. 


Left argument: When [JPLOCK is used with two 
arguments, the left argument is a namelist. (See 
the discussion of namelists at the beginning of this 
chapter. ) 


Each of the names must be well formed. More- 
over, each name must be a name which is present 
in package Y and is there used as the name of a 
function. It doesn’t matter whether or not the 
function in Y is locked already. 


Result: A package containing the same names 
with the same referents as package Y, except that 
those functions which were unlocked in Y and 
were named in X (when you use DPLOCK with two 
arguments), or all functions (when you use 
OPLOCK with one argument), become locked func- 


tions in the resulting package. 
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Chapter 30: 


SESSION 
VARIABLES 





SESSION VARIABLES 


Session variables are the only exception to the rule 
that clearing the active workspace, or loading a 
saved workspace, completely replaces everything in 
the active workspace. The value of a session varia- 
ble lasts throughout a work session (that is, the 
entire duration of a T-task, N-task, or B-task). In 
particular, the value of a session variable survives 
a load or clear. However, the value of a session 
variable does not survive a system error that clears 
the workspace. 


SHARP APL includes two session variables. They 
are denoted by the distinguished names QSP (for 
“session parameter”) and DAT (for “horizontal 
tabs”). (JSP provides a mechanism to transfer in- 
formation from one active workspace to the active 
workspace that succeeds it at a load or clear. 
HT is used to inform the system of the setting of 
horizontal tabs on the terminal you are using. 


























DSP<Y Session parameter 





Meaningful value of QSP: The system imposes 
no restriction on the value of DSP. (JSP exists solely 
as a communication device. The system automati- 
cally copies it forward to the succeeding active 
workspace, but does not inspect or act on its con- 
tents in any way. From that point of view, OSP 
is a variable like any other; it may be any array 
or package. 


Value of DSP following a load or clear: Imme- 
diately following execution of the functions 
DZOAD or QQ@LOAD, or of the commands )LOAD or 
)CLEAR, the system sets the visible value of DSP 
in the new workspace to the visible value of DSP 
in the preceding active workspace. It does that 
even before it executes the latent expression of a 
newly-loaded workspace. 


Only the visible (that is, most local) value of 
USP is involved. If there were other, more global 
values of DSP in the preceding workspace, they are 
lost. If there are other, more global values of 
LISP in the workspace being loaded, they are un- 
changed from the values they had when the work- 
space was saved. 





Value of (SP at the start of a task: At the start 
of every T-task, DSP is an empty vector. That is 
true even when the system automatically loads the 
workspace CONTINUE at sign-on (because the 
preceding T-task ended without a normal sign- 
off). 


At the start of an N-task, DSP has the same value 
that it had in the active workspace of the parent 
task. 


At the start of a B-task, the value of OSP depends 
on what you did about the B-task parameter 
COPYSP at the time you submitted the B-task re- 
quest. When you elect the option COPYSP, the visi- 
ble value of [SP in the workspace that submits the 
request is copied into the B-task’s active workspace 
when it starts. But this happens only when the 
B-task is first started; if the B-task is interrupted 
and restarted for any reason, that constitutes a 
new task. The former value of OSP is not copied 
forward, and the visible value of [SP is again an 
empty vector. 


Recommended use of DSP: The system variable 
DSP exists solely to permit you to pass information 
from the active workspace to its successor. That 
successor might be your own active workspace a 
moment later, following your use of DLOAD or 
QQLOAD. Or it might be an N-task or a B-task that 
you dispatch from your active workspace. 


In any of those situations, you should set a value 
for DSP as late as possible before you start the new 
workspace. The new workspace should immediate- 
ly read the value of DSP, and store it in some other 
form (for example, as the value of some other 
variable). 


The point is that you should not use DSP for 
protracted storage, but solely to communicate 
across the transition from the present active work- 
space to its successor. You should minimize the 
time that this communication is dependent upon 
DSP because, in the event that your task is termi- 
nated prematurely (for example, by a communica- 
tions failure during a T-task, or by any sort of 
error or failure during an N-task or B-task), the 
value of OSP will be terminated with it. A subse- 
quent session which restarts the interrupted work 
is nevertheless a new session, and will not have 
the value of [ISP from your previous session. 


To minimize the interval over which communica- 
tion is dependent on (JSP, you should set things up 
so that the last executed line in the active work- 
space is something like this: 


OSP+SP © Q@LOAD NEWAWS 


Control then passes to [LX of the new workspace. 
Therefore, you should arrange its [JZX so that it 
consists of a line something like this: 


SP]SP © OLX<RESTARTLX © WORK 


Space needed for (SP: If DSP in the present 
active workspace is large, while the workspace you 
propose to load has little free space, it’s possible 
that there wouldn’t be space for JSP in the new 
workspace. The system checks that before it actu- 
ally loads the workspace. If there isn’t going to be 
room, it displays the error message WS FULL and 
does not load the workspace you requested. 


Localization of (SP: You can make DSP local 
to a function, just as you can any variable. While 
a function with a local [JSP is active, only the most 
local value of [SP is visible; any more global val- 
ues are “shadowed.” At each CLEAR or LOAD, 
the system carries forward only one value from the 
old active workspace to the new one. The value 
of SP that is carried forward is the visible (that 
is, most local) one. It becomes the visible (that is, 
most local) value of (SP in the new workspace. 


Retrieving [JSP from a saved workspace: You 
may need to know what value [JSP has in a work- 
space that has been saved. That situation might 
arise, for instance, when the workspace was saved 
at the termination of an N-task or B-task, or fol- 
lowing a communications failure during a T-task. 


Loading the saved workspace won’t do it! The 
value of [SP is indeed saved in the workspace, but 
as soon as you load the workspace, the system 
copies forward the value of DSP from your imme- 
diately preceding active workspace, and that re- 
places the value that DSP has in the saved work- 
space. 
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You can retrieve the global value of DSP from a 
saved workspace by using the command )COPY. 
The command )COPY will copy the global value 
of a system variable from a saved workspace, pro- 
vided the variable is explicitly mentioned in the 
command. That is, you’d have to use 


\COPY CONTINUE [SP 
rather than 


)COPY CONTINUE 


If DSP has been localized in the saved workspace, 
there’s no way of recovering its most local value. 


OHT+Y Horizontal tabs 

The value you give to the system variable XT 
informs the system of the positions at which hori- 
zontal tab stops are set on the terminal you are 
using. The system uses this information in two 
ways: 


1. To interpret your use of the TAB key during 
input. 


2. To calculate an efficient way to transmit a dis- 
play that includes a succession of blanks. 


Responsibility for setting tabs: It’s your re- 
sponsibility to set tabs on your terminal, and then 
to inform the system of the settings you’ve made. 
At some kinds of terminals, it is possible to use 
OARBOUT to send a transmission that has the effect 
of setting tabs, but the system never attempts that 
automatically. 


Index origin of tabs: For the purpose of inter- 
preting DXT, the system always considers the first 
printing position to be position 0. That corre- 
sponds to the almost universal practice of manu- 
facturers of typewriters. But you should be aware 
that a few typewriter-like devices and a greater 
number of video terminals are marked as if the 
first display position were position 1. The system 
always treats the first display position to be posi- 
tion 0, regardless of the type of terminal you may 
be using. 
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With the 0-origin counting employed in interpret- 
ing DHT, a tab stop at position 6 indicates that, 
after one tab from the left margin, the cursor will 
be displaced by six positions, and hence will be 
ready to display a character at the seventh posi- 
tion. (In 0-origin, the seventh position is called 
position 6.) 


The system’s interpretation of DHT is unaffected by 
the workspace index origin DIO. 


Meaningful values: The system requires that 
the value of DHT be a non-negative integer scalar 
or vector. 


When [DAT is a vector, it must consist of distinct 
non-negative integers in ascending order, indicat- 
ing the positions at which tabs are set. It doesn’t 
matter whether or not you explicitly include the 
left margin (position 0) as one of the tabs. 


When DAT is a scalar and has a value greater than 
zero, the system interpets it as if tabs were set at 
every multiple of that scalar, without regard to 


DPW. 


Value of DAT at the start of a task: At the start 
of every task (T-task, N-task, or B-task), the sys- 
tem sets the visible value of DHT to be an empty 
vector, meaning that no tabs are set. As long as 
that value prevails, the system will not use tabs 
during displays, and cannot interpet your use of 
the TAB key during input. 


Effect of DHT on input: Each time you press the 
TAB key, the system substitutes for it a number 
of blanks. The number of blanks is the difference 
between the position of the cursor before you 
pressed TAB, and the next higher value of DHT. 
The tab character itself is explicitly represented in 
the input received at the workspace only when 


you use JARBIN. 


When in the course of making an entry (other 
than a response to DARBIN) you press the TAB 
key at a time when DHT is a vector which doesn’t 
indicate a tab setting to which the cursor could 
move, the system is unable to interpret the input, 
and rejects it with the message CHAR ERROR. 


Effect of DAT on display: When DHT is an 
empty vector or a scalar zero, or when [AT is 
undefined, the system transmits terminal displays 
without making any use of tabs. 


When [HT indicates that tab stops are set, the 
system calculates for itself the most efficient com- 
bination of blanks and tabs. Depending upon the 
type of terminal you’re using, the system may have 
to insert a number of idles after the tab character. 
The idles allow time for the physical repositioning 
of the cursor. 


With certain terminals, the system may judge it 
efficient to tab to a location beyond the position 
you want and then back up to the correct place. 
But the system performs such calculations auto- 
matically. Your only responsibility is to inform it 
what type of terminal you are using (by using the 
system command )TERM), and where your termi- 
nal’s tab stops have been set. 


If you set DHT to something outside the domain of 
possible tab settings, the next time the system 
needs to transmit a display to the terminal, it finds 
it is unable to perform its tab calculation, displays 


the message [HT ERROR, and halts. 
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Chapter 31: 


SYSTEM VARIABLE 
AND FUNCTIONS 
FOR SHARING 
VARIABLES 





RSVR Y Shared-variable query 


Argument: Either an empty vector or a proces- 
sor ID. When the argument is a processor ID, it 
may be a 2-element numeric vector, or else a sin- 
gle number—either a scalar or a 1-element vector. 
A single number is understood to imply a clone 
ID of 0. The values in the right argument must 
be non-negative integers. 


Effect: Any use of SVQ implies the existence of 
a unique processor ID. Where there are active 
workspaces belonging to other tasks running con- 
currently under the same account number, and 
also making use of shared variables, your work- 
space must have established a unique clone ID. If 
this has not been done, the system rejects your use 
of mA) with the error message 
IDENTIFICATION IN USE. 


Result when the argument is empty: When the 
argument of SVQ is an empty vector, the result 
is a numeric matrix containing the processor IDs 
of all processors who have outstanding (that is, 
unaccepted) offers to share with you. The result 
matrix has as many rows as there are distinct 
processors making offers, and two columns. The 
first column is the account number of the processor 
making the offer, and the second is its clone ID. 


Result when the argument is not empty: A 
character matrix of names offered by the processor 
identified in the right argument. 


The matrix has a row for each name the processor 
has offered but you’ve not accepted. There are as 
many columns as necessary to accommodate the 
longest name. 


If the processor identified in the argument has no 
outstanding offers, or if the argument (although 
a plausible processor ID) does not, in fact, identify 
an offering processor, the result is an empty ma- 
trix. 
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ROSVN Y Set clone ID to Y 

Argument: A non-negative integer scalar. The 
proposed clone ID must not conflict with the clone 
ID of another workspace running under the same 
account number. 


Effect: Provided the proposed clone ID does not 
conflict with another clone ID currently estab- 
lished for another workspace running on the same 
account number, and provided this workspace’s 
clone ID has not been frozen, DSVN sets the active 
workspace’s clone ID to Y. (The clone ID is fro- 
zen once the active workspace makes any use of 
OSV@ or dyadic OSVO.) 


Watch out: There’s no way to survey the clone 
IDs adopted by other active workspaces. Applica- 
tions which require an appropriate clone ID are 
presumed to adopt, in advance, a convention gov- 
erning what clone ID they will use. 


Result: When the clone ID was set successfully, 
the result is the new clone ID, Y. When the clone 
ID had already been frozen, the result is the fro- 
zen clone ID. When the proposed clone ID con- 
flicts with a clone ID currently in use by another 
workspace running on the same account number, 


the result is 1. 


Note that when the argument of OSVN is 1, the 
result is the current clone ID. 


Re (QSVO Y 
ReX DSVO Y 


Shared-variable coupling 
Shared-variable offer 


Right argument: A character array of names. 
The array is generally a matrix, with one row for 
each name. Where the argument contains a single 
name, it may be a vector, or, if the name contains 
only a single character, a scalar. 


Each name may be stated alone (on a single row 
of the matrix), or paired with its surrogate. Where 
two names occur on a single row (or where the 
argument is a vector of two names), they must be 
separated by at least one blank. The first name 
is the name used within the task’s workspace, and 
the second name is a surrogate. A surrogate name 
is the name which the system uses to match your 
offer with the offer made by another processor. 
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Each of the names you propose must be well 
formed. Either it must be a name that has no 
visible use, or it may already be in use as the name 
of a variable. Thus, it can’t be a label or the name 
of a function. 


A surrogate name may be any well-formed name, 
regardless of what significance it may have within 
your workspace. 


When you use [SVO monadically, it isn’t necessary 
to repeat a name’s surrogate. However, if you do 
include the surrogate, you must spell it correctly. 
The system won’t recognize a name, even when 
it’s spelled correctly, if you pair it with an incor- 
rect surrogate. 


Left argument: When the function is used 
dyadically, its left argument is a numeric array of 
the processor IDs indicating to whom the names 
in the right argument are offered. 


If the left argument is a scalar or a 1-element 
vector, the system assumes a clone ID of 0. In 
general, the left argument is a 2-column matrix, 
with one row for each processor ID. The first 
column contains the processor’s account number, 
and the second column its clone ID. Each element 
must be a non-negative integer. 


The left argument must contain one processor ID 
for each name (or pair of names) in the right 
argument. However, if the left argument consists 
of a single processor ID (as a scalar or single- 
element vector with an implicit clone ID of 0), it 
is presumed to apply to each of the names in the 
right argument. 


Watch out: If you use a 2-element vector, the 
system interprets that as two distinct processors, 
each with a clone ID of 0, and not as a single 
processor ID. 


Effect of monadic DSVO: None. 


Effect of dyadic [SVO: Each of the names (or 
surrogate names) in the right argument is offered 
to the processor (or processors) identified in the 
left argument. Reiterating an offer of the same 
name to the same partner is harmless, and has no 
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new effect. The system does not accept a new offer 
(that is, of the same name to a different partner) 
until you retract the first offer. 


Making a shared variable offer implies that the 
active workspace can be uniquely identified. It 
must have a clone ID distinct from the clone ID 
in use by any other processor which has the same 
account number, is now running, and is making 
use of shared variables. If you need a distinct clone 
ID but haven’t set one, the system rejects your use 
of dyadic OSVO with the error message 
IDENTIFICATION IN USE. 


While you have at least one name whose degree 
of coupling is at least 1, your clone ID is frozen. 
If you haven’t explicitly set a clone ID, sharing 
a variable has the effect of freezing your clone ID 
at 0. 


Result of 0SVO: A numeric vector indicating the 
degree of coupling of each of the names (or name 
pairs) in the right argument. For dyadic QSVO, 
this is the degree of coupling produced by the 
offer. 


Coupling is reported according to the following 
code: 


0 No coupling (or not a well-formed name) 

1 Offer extended by one partner but not ac- 
cepted 

2 Reciprocal offers by both partners; sharing 
in effect 

RSVS Y State of variables named in Y 


Argument: A character array of names. In gen- 
eral, the argument is a matrix, with one row for 
each name. Where the argument contains a single 
name, it may be a vector, or, if the name contains 
only a single character, a scalar. 


Each name may be stated alone (on a single row 
of the matrix), or paired with its surrogate. Where 
a name and its surrogate occur on a single row 
(or where the argument is a vector of two names), 
they must be separated by at least one blank. The 
first name is the name used within the workspace; 


the last name is the surrogate. A surrogate name 
is the name which your partner must offer instead 
of the name you use within your workspace. You 
don’t need to include the surrogate name, but if 
you do, it must be correct. The system won’t rec- 
ognize a name, even when it’s spelled correctly, if 
you pair it with an incorrect surrogate. 


Result: A Boolean array. Where the argument 
was a matrix, the result is a 4-column matrix 
having as many rows as the argument. Where the 
argument was a vector or a scalar, the result is a 
4-element vector. 


The result indicates the state of each of the names 
(or name pairs) in the right argument. A row of 
the result may have any of the following four pos- 
sible values: 
0011 Both processors are aware of the 
current value of the shared varia- 
ble. 


You have set a new value of the 
shared variable, but your partner 
has not used it. 


1o10 


0101 Your partner has set a new value 
for the shared variable, but you 
have not used it. 

0000 The corresponding name in the 
right argument does not identify a 


shared variable. 


Set access control for names 
Y to X 

ke [SVC Y Report access control for 
names Y 


R-X (SVC Y 


Right argument: Same as for (ISVS. 


Left argument: When the function is used 
dyadically, the left argument is a Boolean array 
containing the proposed new values for control 
vectors matching each of the names appearing in 
the right argument. 


In general, the left argument is a 4-column matrix, 
containing as many rows as there are rows in the 
right argument. However, the left argument may 
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contain only one access control vector, in which 
case it may appear either as a 1-by-4 matrix or 
as a 4-element vector. 


When the left argument contains only one vector, 
but the right argument contains several rows, the 
same control vector is applied to each of the names 
on the various rows. 


The left argument may also be a scalar or a 1- 
element vector. In that case, the system treats the 
argument as if it were a 4-element vector having 
the same value throughout. 


Effect of monadic (SVC: None. 


Effect of dyadic [ISVC: For each of the names 
in the right argument that represents a currently 
visible shared variable, the control vector is reset. 
A 1 in each of the four positions of the control 
vector inhibits action as follows: 


Your Partner 


Your Partner You 





The new setting is the value stated in the corre- 
sponding row of the left argument OR-ed with the 
value most recently set by the other partner. (The 
effect of this rule is that you cannot reset elements 
of the control vector which your partner has set 
to 1.) 


Result: The current effective value of the control 
vector for each of the variables named. For dyadic 
use of DSVC, that is the value following execution 
of the function. 


Where a name in the right argument is not a 
shared variable, or is not a well-formed name, the 
corresponding row of the result is 0 O 0 O. 


Retract share-offer of names 
in Y 


R+e)SVR Y 


Argument: Same as for [JSVS. 


Effect: Where the visible referent of a name in 
Y is a shared variable, sharing is discontinued. 
This has no effect on the value of the shared varia- 
ble. Retraction is recorded as a state change, and 
causes the system to set DSC. This may be detected 
by the other partner. Following discontinuation of 
sharing, the variable’s control vector and state vec- 
tor are both reported as 0 0 0 O. 


Where the visible use of the name is an offer 
which has not been accepted, the offer is with- 
drawn. Withdrawal of an unaccepted offer does 
not count as a state change, and has no effect on 
the name’s control vector or state vector, which 
remain 0 0 0 0. 


Where there is no visible use of the name, or it 
is not a well-formed name, there is no effect. 


Result: The degree of coupling of the variable 
before the offer was withdrawn. This is recorded 
as 2 for a variable that was shared; 1 for a name 
which you had offered but which had not been 
accepted; and 0 for an item that had not been 
offered or was not a well-formed name. 


RSC State change variable 

This variable is automatically shared with the sys- 
tem. Any time you refer to it, the value you see 
is one set by the system. Its value may be a scalar 
1 or 0. 


When your active workspace has not established 
a valid clone ID (by use of DSVN, or implicitly by 
use of QSVQ or dyadic QSVO), each time you use 
OSC, the system immediately assigns it the value 
0. 


Once your workspace has established a valid clone 
ID, your use of the variable OSC is interlocked by 
the system. Thereafter, each time there is some 
change in the shared-variable state of your work- 
space, the system sets the value of JSC to 1. But 
if there has been no change since the last time 
you used [JSC (or since you started using 
shared variables), the system delays supplying 
that value 1 until a state change occurs. You’ll 
experience an indefinite delay until the state 
change. 
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A change in the shared-variable state arises from 
any of the following: 


1. When your partner retracts a variable you 
were sharing. 


2. When a processor specifically directs a new 
offer to share to your active workspace. 


3. When any of your shared variable partners 
takes an action that alters the result of OSVS or 
OSVC with respect to any variable you are now 
sharing. (Notice that a state change might be 
produced by something your partner does to a var- 
iable which is shadowed in your workspace, so 
that the variable is not now visible to you.) 


You can interrupt the delay imposed during an 
attempt to use DSC by signalling an interrupt (two 
consecutive uses of BREAK or ATTN). 


If you use SC when you have not yet used the 
shared variable functions DSVN, OSVQ, or dyadic 
OSVO, you'll receive the value of OSC immediately. 


Value of DSC when used: The value of [JSC is 
a scalar 1 when the workspace has a valid clone 


ID, and 0 otherwise. 
$ 
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Chapter 32: 


SYSTEM FUNCTION 
AND VARIABLES 
AFFECTING 

THE WORKSPACE 
ENVIRONMENT 





OLX+Y Latent expression 


Each time it loads a workspace, the system auto- 
matically executes the expression it finds stored in 
the workspace as the value of the character vector 
DLX. Whatever expression is in (ZX when a work- 
space is saved, is thereafter executed automatically 
each time that workspace is loaded. 


The fact that the system treats the variable [LX 
in this way lets you have work started immediate- 
ly, and without intervention from whoever is load- 
ing the workspace. That ability has a number of 
uses, among them the following: 


1. Convenience: You don’t have to take addi- 
tional steps to get work started. 


2. Security: The instruction contained in the la- 
tent expression may initiate checks or keep 
records, without the user’s intervention (or even 
knowledge). 


3. Linkage: When an application uses JZOAD or 
LIQLOAD to make active a different workspace, con- 
trol passes to the latent expression of the newly 
loaded workspace. In that situation, it’s essential 
to prepare in advance an appropriate DZY, so that 
the loaded workspace can take over from the 
workspace that invoked it. 


4. Batch task: For all B-task requests, and for 
those N-tasks that start by loading a workspace, 
the system relies on (LX to provide the first in- 
struction for the task. 


Timing of execution of DLX: Immediately after 
it loads a workspace, the system embarks automat- 
ically upon the following two steps: 

1. It copies forward the value of the session varia- 
bles QSP and QAT from the preceding active work- 


space. 


2. It executes the latent expression [JLX. 
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Domain of (ZX: The system executes LX by 
generating the statement #{)LX. Thus, OLX must 
contain an array that is acceptable as an argument 
to @. 


When (LX is an empty vector, ¢0ZX has no effect. 


When [ZX is not empty, it must be a character 
scalar or vector representing a line of APL. The 
system executes it in the same way that it would 
if you entered it from the keyboard for immediate 
execution. 


When the expression in QZX contains an error, the 
system reports it in the usual way. 


Localization of (ZX: As with any variable (in- 
cluding system variables), you can make QZX local 
to a function. It is always the visible referent of 


OLX which is executed when a workspace is load- 
ed. 


Making (LX local to a function is a possible ap- 
proach to making a task restartable, although not 
necessarily the best one. You might create a global 
OLX which starts an application. Each of the vari- 
ous functions called by the main function may, if 
need be, have its own DZX, which will be effective 
only if the task is interrupted and the workspace 
saved while that particular QZX is the visible one 
and has a value. This and other approaches to 
restartability are discussed in the publication 
“Batch Tasks in SHARP APL.” 


Initial value of (ZX: In a clear workspace, the 
global value of DLX is an empty vector. 


If, when a workspace is loaded, the system finds 
that no value of QZX is visible (for example, be- 
cause it has been erased, or because it is local to 
a suspended function in which no value has been 
assigned to it), the system responds as though 
OZX were an empty vector. It does not halt, and 
does not report an error. 


Effect of (ZX on the state indicator: Each time 
a workspace is loaded, the system generates the 
instruction 402X. The symbol 2 is inserted as the 
top row of the state indicator, and the number 0 
as the first element of DZC. If you put into DLX 
an instruction to resume work at the point it was 
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interrupted, you'll need to allow for those inser- 
tions, by an instruction such as 


OLX+'>14+0LC' 


rather than merely '>DLC'. 


Ocr+y Comparison tolerance 


The system refers to the visible value of OCT while 
evaluating the following functions: 


X=Y Y 
XzY LY 
X<Y 
X<Y 
X2Y 
X>Y 
Xey 
XiY 
X\Y 


When [CT is 0, two values are considered equal 
only if their internal representations are exactly 
equal. 


When [CT is greater than 0, comparisons are 
“fuzzed,” according to a procedure described in 
Chapter 14. This permits two values that are rela- 
tively close (and whose difference may well have 
arisen as a consequence of imprecisions of compu- 
tation) to be treated as equal, and a value that is 
relatively close to an integer to be rounded to that 
integer. The system requires that OCT be a non- 
negative scalar (or i-element vector) less than 
16* 8 (which is about 2.328306437E 10). 
The value of OCT in a clear workspace is 
1.419697693E 14, meaning that two values, or 
a value and an integer, are judged equal if the 
magnitude of their difference is within [CT times 
the magnitude of the one having the larger magni- 
tude. 


RDL Y Delay Y seconds 

This function doesn’t do any work, but causes a 
delay in execution in your active workspace, at 
negligible CPU cost. It is useful when you want 
a function to check periodically the status of some 


external condition from which you can’t receive a 
direct signal. For example, suppose you’re writing 
a trap definition for a problem that you believe 
may be transitory. You’d like to wait a reasonable 
interval, and try again. 


Argument: A numeric scalar (or 1-element vec- 
tor) indicating the number of seconds of delay you 
want before execution resumes in your active 
workspace. The value may not be negative. 


Effect: Execution in your active workspace is 
suspended until the indicated time interval has 
elapsed. During that time, nothing takes place in 
the active workspace. If you change your mind 
while the workspace is in that state of idleness, 
you can transmit an attention signal (by a single 
use of BREAK or ATTN). 


Result: The actual number of elapsed seconds 
until work resumes or the delay is interrupted. 
Provided you don’t interrupt the delay, the system 
never resumes execution sooner than the end of the 
interval you requested. On the other hand, de- 
pending on its load, the system may, in fact, re- 
sume after an interval slightly longer than you 
requested. Hence, the result of [DL Y is at least 
Y, but may be greater. 


Watch out: Using ODZ isn’t the way to produce 
a small pause in a display at your terminal. Out- 
put to terminals is buffered, and may lag consider- 
ably behind activity in the workspace. Moreover, 
if your terminal is remote from the computer 
centre, there may be additional delays in transmis- 
sion. Thus, a small delay in processing at the 
workspace, at a time when there’s a lot of display, 
may be imperceptible at the terminal. A small 
delay in display at a terminal is better produced 
by transmitting idles. 


Watch out: When you want to delay until some 
external event occurs and that event can be signal- 
led by a change in the state of a shared variable, 
it is probably preferable to use the system variable 
OSC to delay indefinitely until a state change oc- 
curs. That’s probably more efficient than using 
DDZ to poll repeatedly. See the discussion of “state 
change” in the chapter on shared variables. 


nw 


OIo+y Index origin 


The index origin is the first counting number. For 
example, when the index origin is zero, the first 
three integers are considered to be 0 1 2, whereas 
when the index origin is 1, the first three integers 
are considered to be 1 2 3. 


Functions subject to 70: The following mo- 
nadic functions must refer to DIO in order to re- 
turn a result: 


1Y 
?Y 
AY 
VY 


All uses of indexing depend on having a value for 
the index origin. A valid DIO is required before 
any use of the following dyadic functions: 


XXY 
XY 
X(Y] 


A valid DIO is required before any use of the axis 
operator. The axis operator applies to the follow- 
ing functions: 


CI] Y Reverse 
XLI] Y Rotate 
X/[I] Y Compress 
AS Expand 
X,[I] Y Catenate or laminate 
f/[I] Y Reduce (by any dyadic scalar 
function indicated by f) 
f\(I] Y Scan (by any dyadic scalar 


function indicated by f) 


Meaningful values of D70: The system will not 
stop you from setting DZO to anything you like. 
However, when the system evaluates any of the 
functions or operators subject to ZO, DIO must be 
a scalar (or a 1-element vector), and must have 
either the value 0 or the value 1. If it has any 
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other shape, or any other value, the system rejects 
the statement with the message DIO ERROR. 


Initial value: 
DIO is 1. 


In a clear workspace, the value of 


You can make DIO local to a function. While that 
function is active, the value to which (ZO is set 
within that function is the one that prevails. If you 
localize QIO but fail to set it before you make use 
of a function that requires it, the system rejects the 
statement with the message [JO ERROR. 


DRL<Y Random link 

Either monadic or dyadic use of the primitive ?, 
causes the system to generate random integers. 
Strictly speaking, these are pseudo-random num- 
bers. That is, although a collection of them satis- 
fies most tests of randomness, they are generated 
by a deterministic process. Each time the system 
calculates an element of the result of ?, it bases 
its result on the visible value of the system variable 
URL. At the same time, it sets a new value for 


ORL. 


Each time you use ? with the same argument and 
the same value of ORZ (and also of DIO), you'll 
get the same result. When you save a workspace, 
the value of [RL (like that of any variable) is 
saved as part of it. Each time that saved workspace 
is loaded, the same uses of ? will yield the same 
results. 


There are two reasons you might want to set a 
new value of [IRL before making use of the random 
function ?: 


1. To assure that the results are the same as on 
some other occasion (for example, when you want 
to reproduce exactly a test that was conducted ear- 
lier). 


2. To assure that results are not the same (for 
example, when you repeatedly load a workspace 
but want the random numbers it produces to be 
different each time). 
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aanne 


For the first situation, you need to set DRL to 
whatever value it had before. For the second situa- 
tion, you need to set it to something unpredictable; 
for example: 


ORL+(+/O7S)+x/3+O7s+1 


Initial value of DRL: 
value of [RL is 16807. 


In a clear workspace, the 


Effect on DRL of using ?: Each use of the ran- 
dom-number generator sets a new value of QRZ. 


The procedure by which the system generates a 
new pseudo-random number involves two con- 
stants. The first is the multiplier, M+16807, and 
the second is a prime, P<2147483647. (The 
prime is in fact a Mersenne prime, being 
~1+2*31.) 


At each cycle of use of the random-number gener- 
ator, the visible value of DRZ is reset by the follow- 
ing formula: 


ORL-P |MxQRL 


When you use ? with a right argument greater 
than P, each element of the result requires two 
cycles, and so then the new value of (JRL is ob- 
tained by: 


ORL<P | MxP | MxORL 


Meaningful values of (RZ: The system will not 
stop you from setting [RL to anything you want. 
However, when the system evaluates either mo- 
nadic or dyadic ?, ORZ must be a scalar (or 1- 
element vector) whose value is an integer greater 


than O and less than ~1+2*31, which is 
2147483647. 
OPP+Y Print precision 


If you don’t say how many significant digits you 
want in a display, the system uses the visible value 


of DPP. 


Initial value: 
space is 10. 


The value of [IPP in a clear work- 


~— 


Meaningful values of DPP: The system will not 
stop you from setting [PP to anything you want. 
However, whenever the system must prepare a 
numeric display without explicit formatting in- 
structions, or evaluate a monadic use of +, [PP 
must exist, must be a scalar or 1-element vector, 
and must be an integer greater than 0 and not 
greater than 18. 


DPW<-Y Print width 
The system variable [JPW controls the maximum 
number of characters per line transmitted to a 
terminal during normal output. 


For most purposes, this has the effect of control- 
ling where the system “folds” what would other- 
wise be a continuous line of output, to accommo- 
date DPW. The setting of OPW usually (but not 
necessarily ) reflects the physical size of the display 
on the kind of terminal you’re using. 


The system keeps track of the position of the cur- 
sor during default output, and output produced by 
expressions such as [}+Y or [-Y. Movement of the 
cursor in response to JARBOUT or [JARBIN is not 
accounted for, so if you intersperse such output 
with normal output, the system’s control of print 
width may be invalidated. 


Effect of [PW on display: When as a conse- 
quence of normal output, the cursor is located 
OPW printing positions from the left margin and 
there remains more of the current row of output 
to be displayed, the system sends a “new line” 
signal, and then six blanks. Thus, it does not dis- 
play more than QZW characters on a line, and con- 
tinuation lines are indented six spaces from the left 
margin. 


When the system is displaying numeric data, it 
folds the line at a position where there is a blank 
separating successive elements of the array being 
displayed. In that case, the line may be folded 
sooner than at position OPW. (Note that the result 
of + or (FMT is character data, not numeric.) 


When it is displaying character data, the system 
simply folds the line when [JPW characters have 
been displayed, without attempting to fold at a 
blank. 


aca 


When the system is displaying the definition of a 
function with the V function editor, the line is 
folded so as to avoid separating the successive 
characters of a name, or the digits of a numeric 
constant. 


Effect of DPW on line editing: When you are 
using the system line editor, either within the V 
function editor, or to edit the preceding APL line 
entered for immediate execution, you can’t request 
a display or generate a line longer than DPW char- 
acters. If you attempt to do so, the system reports 
a CHAR ERROR, and displays the first DPW charac- 
ters of the line. It leaves the cursor at the end of 
the line, so that you may accept it as it is, or 
backspace and correct parts further to the left. 


Effect of DPW on input: The setting of [PW does 
not affect input from the keyboard (except as it 
may imply output for the line editor). However, 
the system imposes a limit on input per entry. 
That limit is 256 effective characters for input 
other than JARBIN, and 500 keystrokes (or other 
signals) during input in response to QARBIN. 


Initial value of OPW: The global value of DPW 
in a clear workspace is 132. 


Meaningful values of (PW: The system won’t 
stop you from assigning to JPW any value you 
want. However, during any normal display (that 
is, a display resulting from default output, or from 
use of [+Y or M-Y), the system requires that 
OPW exist, that it be a scalar or a 1-element vector, 
and that it be an integer not less than 30, nor 
more than 250. 


Displays not subject to DPW: The system makes 
no attempt to keep track of the effects of arbitrary 
output on the cursor. 


Terminal-to-terminal messages, either from anoth- 
er user or from the system Operator, are not sub- 
ject to DPW. 


When [PW is not set, or is set improperly, the 
system still transmits error messages. It bases its 
transmission of error messages on the most recent 


valid value of (PW used during the session. 
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Chapter 33: In addition to the APL language, the SHARP 
APL system also supports a body of commands 
that you can address directly to the system. These 


SYST EM COM M ANDS are called system commands. 


System commands are not considered to be part of 
the APL language. They differ from it (and some- 
times from each other) in their conventions re- 
garding arguments, syntax, etc. They cover a wide 
variety of actions. 


System commands have the following in common: 


1. A system command can be used only by enter- 
ing it manually, from the keyboard, and only 
while you’re in immediate execution mode (or in 


O input). 


2. Every system command starts with a right pa- 
renthesis. Moreover, when it’s in immediate exe- 
cution mode, the system treats any entry from the 
keyboard whose first non-blank character is ) as 
an attempt to enter a system command. 


3. The system either executes a system command 
or it doesn’t. Once it has started to execute a com- 
mand, it can’t be interrupted in mid-execution. 
However, the display resulting from some system 
commands can be cut short by signalling attention. 


4. The display the system sends to your terminal 
when it executes a command is not APL data. It 
can’t be used as the argument of a function, nor 
as the response to a request for [] input. When you 
set (OUT to record terminal output in a file, dis- 


plays produced by system commands are not in- 
cluded. 
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Commands and functions that do similar work: 
For certain system commands, there exist also sys- 
tem functions that do more or less the same thing. 
Over the years there has been a general tendency 
to supplant system commands by system functions 
that provide similar or related services. Some of 
the commands that were in use several years ago 
(for example, )ORIGIN, )DIGITS, or )WIDTH) 
have been replaced by system variables (in the 
examples, by (70, QPP and DPW, respectively). 


In the text that follows, each command is illus- 
trated by a sample use, and then defined. In the 
sample, material that may be omitted is shown 
enclosed in brackets. Where you’re required to 
choose one or another from a set of alternatives, 
the alternatives are separated by a vertical bar. 


)nnnnnnn[: password] Sign-on 


The sign-on is the way you start a T-task. You 
identify yourself to the system by stating your ac- 
count number and by supplying the password that 
you have previously established. 


Before you can sign on, first you have to initiate 
communication with the system. The procedure 
varies, depending on the device you’re using and 
the way it is linked to the computer. However, 
before you can sign on, you have to do two things: 
identify the type of terminal you are using, and 
request a blot. Generally you can accomplish both 
of those by a single two-character transmission. 
The first character indicates the type of terminal, 
and the second is the request for a blot. The two 
characters are: 


From an ASCII-coded terminal: ©) 
From an IBM correspondence terminal: 9) 


From an IBM BCD terminal: J) 


These conventions apply regardless of the speed at 
which your terminal is transmitting; the device 
that receives this signal determines the speed by 
inspecting the first transmission. For low-speed 
IBM terminals, you may be able to omit the first 
character. 


Having received the initial ), the system prints a 
blot. This provides a zone in which you can write 
your sign-on in a way that it cannot be read by 
others. 


The sign-on itself consists of ) followed by your 
account number (normally seven digits), then a 
colon, and your password. 


Following a correct sign-on, you receive an ac- 
knowledgement from the system. It shows the 
task-number of the T-task you just started, the 
time and date, and the name of the account. At 
the I.P. Sharp Toronto centre, the date and time 
are shown in UTC (coordinated universal time). 
The account name is a sequence of up to eleven 
letters, established when the account was enrolled. 


If your attempted sign-on is in the correct form, 
but the number or the password is wrong, the 
system sends the message NUMBER NOT IN 
SHARP APL SYSTEM and another blot. 


If your attempted sign-on was not in the correct 
form (for example, because it didn’t start with ) 
or used a non-numeric character in the account 
number, or something other than a colon to sepa- 
rate the account number from the password) the 
system sends the message INCORRECT SIGN-ON. 
Frequently the system sends that message because 
you've substituted some other character for colon. 
By way of reminder, the system displays two co- 
lons at the end of that message. 


Whenever you enter ) followed by a number grea- 
ter than (JPW, the system assumes you’re trying to 
sign on. When you’re already signed on, it rejects 
your entry with the message ALREADY SIGNED 
ON SHARP APL SYSTEM. 


) [nn] Line editing 
A right parenthesis standing alone, or followed by 


a number that is not greater than (JPW, is a request 
for line editing. 
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When you enter ) alone or followed by the num- 
ber 0, the system displays the preceding APL line 
entered from the keyboard. Then it turns the key- 
board over to you with the cursor on the same 
line, to the right of the displayed line. You can 
alter the line by appending other characters, or by 
backspacing and correcting the characters the sys- 
tem displayed in the same way as if you’d just 
keyed them in yourself. When you press RE- 
TURN, the entire line, as modified, becomes your 
next APL entry. The system executes it. 


When you enter ) followed by a positive number, 
the system displays the preceding APL line en- 
tered from the keyboard for immediate execution. 
Then it turns the keyboard over to you with the 
cursor on the following line, at the position indi- 
cated by the number to the right of the parenthe- 
sis. Then the system awaits an entry in which you 
indicate how you want the line to be modified. 
The modification instruction works as follows: 


1. When your entry contains a dot or a comma: 


a. Each slash anywhere to the left of the first 
dot or comma indicates a position to be deleted. 


b. All characters to the right of the first dot 
or comma are to be inserted. They will appear to 
the left of the character that’s now above the first 
dot or comma. 


What the system does next depends on whether 
that first dot or comma is a dot or is a comma: 


c. When it’s a comma, the system makes the 
deletions and insertion you’ve indicated, displays 
the line (as modified), and awaits further instruc- 
tions in the same form. It turns the keyboard over 
to you with the cursor positioned below where you 
put the first comma. 


d. When it’s a dot, the system makes the dele- 
tions and insertion you requested, and then imme- 
diately executes the line (as modified) without 
displaying it. 
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2. When the modification entry contains neither 
a dot nor a comma: 


a. Each position marked by a slash is deleted. 


b. Each position marked by a digit or a letter 
of the alphabet has blanks inserted before it. The 
number of blanks is indicated by the digit. When 
you need to insert more than nine blanks, use 
letters of the alphabet according to the following 
code: A for 5, B for 10, and so on. 


The system displays the line, with the deletions 
and spaces you requested. It turns the keyboard 
over to you with the cursor on the same line, at 
the first inserted space. Then the system waits for 
you to overstrike the line it has displayed with the 
characters you want to insert. When you press 
RETURN, the system executes the line as now 
modified. 


) BLOT Print a blot 

Before your next entry from the terminal, the sys- 
tem prints a blot. This is intended to conceal your 
entry, as a security measure. The blot occupies 17 
printing positions starting with position 7. The 
system turns over the keyboard to you with the 
cursor on the same line, at position 7 (that is, at 
the beginning of the blot). 


The entry you make in the blot is executed in the 
usual way. 


)CLEAR Clear the active workspace 
This command discards everything from the active 
workspace except the value of the session variables 
OSP and DHT. The state indicator is made empty, 
and all variables and defined functions vanish. 


Following )CLEAR, the situation of various work- 
space parameters is as follows. 


CONDITION OF WORKSPACE FOLLOWING )CLEAR 


Workspace name 


Workspace password None 


State indicator Empty 


Symbol table capacity 256 


Workspace available, DWA 


None (reported as CLEAR WS) 


Installation dependent; at present in the Sharp Toronto 


system, 257180 minus the space needed for session varia- 


bles 
Session parameter, SP 
Horizontal tabs, DAT 


Latent expression, OLX ws 


Line counter, DLC 10 


Index origin, ZO 1 


Comparison tolerance, [CT 


Random link, ORL 16807 





Print precision, [PP 10 
Print width, OPW 132 
Files tied, (ONAMES and QNUMS) 


Output parameter (set by DOUT) 





) [P]COPY [libno] wsname [:password] [list] 


The COPY command has two forms. Either of 
them lets you copy one or more global objects from 
a saved workspace to your active workspace. 


If you use the command with the prefix P (for 
“protect” ) the system copies an object only if its 
name is not already in use in your active work- 
space as the name of a global object. Thus, an 
existing global function or variable is protected 
from being overwritten by an object copied from 
the saved workspace. 


Unaffected 


Unaffected 


Unaffected 


Unaffected 


1.419697693F 14 


Stating it the other way, without protection, 
)COPY permits a global object that you copy from 
the saved workspace to replace the global object 
having the same name in your active workspace. 


When the saved workspace from which you’re 
copying belongs to a library other than your own, 
you must include its library number preceding its 
workspace name. When the workspace you’re 
copying from is locked, after its name you must 
include a colon and its password. 
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The objects that are copied: When you use 
)COPY or )PCOPY without a list of objects to be 
copied, the system takes that as a request to copy 
all global objects other than system variables from 
the saved workspace. 


When you include a list of one or more names of 
objects to the right of the workspace name, the 
system copies only those objects. The list may in- 
clude the names of system variables. 


If the workspace from which you wish to copy 
doesn’t exist, or requires a password different from 
the one you indicated, the system reports WS NOT 
FOUND or WS LOCKED, as appropriate, and goes no 
further. 


If the workspace is found and you have access to 
it, the system reports the time and date at which 
it was saved. 


If you mentioned the names of specific objects to 
be copied, but those are not the names of global 
objects in the saved workspace, the system displays 
the message WOT FOUND: followed by the names 
of objects that were not found. However, the sys- 
tem goes ahead with copying those objects that it 
can find. 


Objects found but not copied: It may be that 
one or more objects that exist in the saved work- 
space nevertheless are not copied. This happens 
when any of the following conditions is met: 


1. The name is in use in your active workspace 
as the name of an active function (that is, one that 
appears on the state indicator). 


2. The saved workspace from which you’re copy- 


ing is sealed. You can’t copy a locked function 
from a sealed workspace. 


3. You are using )PCOPY rather than )COPY, and 
the name is already in use as the name of a global 
object in your active workspace. 


4. Your active workspace is sealed. When you use 
the command )COPY to copy into a sealed work- 
space, it behaves in the same way as )PCOPY. 
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When an object is not copied for any of those 
reasons, the system displays. the message 
NOT COPIED: followed by the names of the ob- 
jects not copied. However, it goes ahead with the 
copying of other objects. 


Space to accommodate the objects copied: It 
may be that there isn’t room in your active work- 
space to store all the objects you’ve requested. The 
system checks in advance whether there will be 
room for all of them. If it finds there would not 
be room to permit all the objects to be copied, 
none is copied. The system rejects the command 
with the message WS FULL. Although none of the 
objects is copied, the symbol table of the active 
workspace may nevertheless retain unused symbols 
(for objects which were considered but not 
copied ). 


)DROP [libno] wsname [:password] 


This command causes the system to drop one 
saved workspace from its auxiliary storage. It has 
no effect on the active workspace. 


When the workspace is in a library other than 
your own, you have to include the library number. 
However, you may do that only if both of the 
following are true: 


1. The library is a public library (that is, has a 
number less than 1000). 


2. You were the person who saved the workspace. 


When the workspace is locked, you must include 
its password when you request to drop it. If you 
want to drop a locked workspace named OLDWS, 
but no longer know its password, you can still 
drop it by a sequence such as the following: 


)CLEAR 
\WSID OLDWS 
)SAVE 

)DROP OLDWS 


When a saved workspace is dropped, the system 
reports the time and date at which it was dropped. 


)ERASE [list] 


This command erases (or “expunges”—the terms 
are used interchangeably) the global objects listed 
to the right. 


The system reports only the names of those objects 
it did not erase. The system displays their names 
in one or two messages, with the captions 
NOT FOUND: or NOT ERASED:, as appropriate. 


An object is not erased if its name meets any of 
the following criteria: 


1. It is not the name of a global object. 


2. It is in use as the name of an active function 
(that is, a function that appears in the state indi- 
cator). 


3. It is in use as the name of a locked function 
and this is a sealed workspace. 


Note that if you include a valid name more than 
once in the list, the first occurrence will cause it 
to be erased, but the subsequent occurrences will 
generate the message NOT FOUND (because it’s 
been erased). 


)FNS [letters] Functions list 
)VARS [letters] Variables list 


This command causes the system to print a list of 
those names whose visible use is as the name of 
a function ()FNS), or as a variable ()VARS). 


The system displays the list horizontally, and ar- 
ranges the names in alphabetical order. For pur- 
poses of alphabetization, the system considers the 
sequence of letters in the alphabet to be as follows: 


ABCDEFGHIJKLMNOPQRSTUVWXYZ 
0123456789A 
ABCDEFGHITKLIMNOPQRSTUVWXYZA 


Starting the list at a particular letter: If you 
include one or more letters to the right of the 
command )FNS or )VARS, the system starts its 
display at that point in the alphabetical sequence 


wee 


of names. The letters you use for this purpose 
don’t have to be present in the workspace as a 
name. 


Related functions: The display produced by 
)FNS contains the same names as are included in 
the result of DVL 3 or 1 [WS 1. The display 
produced by )VARS contains the same names as 
are included in the result of DNE 2 or 1 [WS 2. 


)KEYB [LOCK|NOMSG] Keyboard control 


The command )KEYB NOMSG prevents you from 
receiving messages sent directly to you from anoth- 
er terminal or from the system Operator. You can 
use this to assure that a message from another user 
or from the system Operator won’t appear in your 
display. Someone who attempts to send you a mes- 
sage by using the command )MSG, sees the re- 
sponse INCOMMUNICADO. 


The command )KEYB LOCK causes the system to 
accept input from your terminal only in response 
to a specific request. To start each entry, you must 
first press BREAK or ATTN, and await indica- 
tion from the computer that it is ready for you to 
proceed. 


At terminals such as the IBM 2741, the keyboard 
is locked and you can’t type until your terminal 
receives that signal. At most ASCII terminals, the 
keyboard is never locked, but the terminal trans- 
mits only what you type after the system signals 
it is ready to receive and, at that time, it also sends 
the signal to sound the bell at your terminal. 


The command )KEYB LOCK is useful primarily 
when you expect to receive messages, and wish to 
leave the terminal free to receive them. 


The command )KEYB ends either of the states 


started by the other two forms of the command, 
and returns the keyboard to normal operation. 


)LIB [libno] List workspaces in library 


This command gives you a list of the saved work- 
spaces currently in a particular library. 
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If you use the command without indicating a li- 
brary number, the system gives you a list of the 
workspaces in your own private library. 


If you include a library number, it must either be 
your own, or the number of an existing public 
library. 


The system displays a list of the workspaces in the 
library you’ve requested, one per line. The list is 
not alphabetical. There is no provision to show 
only part of the list, or to start at a particular 
letter. 


)LOAD [libno] wsname [:password] 


This command replaces the contents of the active 
workspace with a duplicate of a saved workspace. 
This has no effect on the saved workspace. 


When you don’t state a library number, the system 
understands you to mean a workspace from your 
own library. 


If the workspace is locked, after its name you must 
include a colon and its password. 


Session variables and latent expression: Before 
complying with the command to load the work- 
space, the system verifies that there will be suffi- 
cient space to bring forward the current visible 
values of the session variables [SP and (AT. If 
there isn’t room, the system sends the message 
WS FULL and does not load the workspace. If the 
saved workspace has a full symbol table and has 
no DHT and OSP (because it was saved before they 
were introduced into the system), you'll get the 
message SYMBOL TABLE FULL when you load the 
workspace; you can copy the saved workspace into 
a clear workspace with a larger symbol table. 


When the workspace is loaded, the system imme- 
diately copies into it the preceding visible values 
of the session variables JSP and [HT so that the 
visible values they had in the former active work- 
space become their visible values in the new active 
workspace. Then the system executes the latent 
expression by automatically generating and 
executing the instruction 2[)LX. 
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Name of the active workspace: When the sys- 
tem loads a workspace into your active area, it 
keeps a record of the workspace’s name. You can 
use the command )WSID to display the current 
name, or to rename it. The system refers to its 
record of the current name of the active workspace 
to decide what name you mean when you use the 
command )SAVE with no name indicated. 


The system function 2 [WS 1 also returns the 
current names of the active workspace. However, 
the second and third elements of the result of 
2 (WS 4 report the owner and original save date, 
regardless of changes in the current name. 


)MSG[N] taskno [text] 
)OPR[N] [text] 


You can use the command )MSG or )MSGN to send 
a one-line message to the terminal of another per- 
son who’s currently signed on. 


The recipient is identified by task number. The 
task number appears in the command separated 
from the name of the command by a space. (You 
can use the command )PORT to find out what a 
particular user’s current task number is.) 


Following the task number, and separated from it 
by a space, you may write any text, provided only 
that it is composed entirely of characters accepta- 
ble by the APL system. 


The commands )OPR and )OPRN work in exactly 
the same way as )MSG and )MSGN, except that the 
recipient is the system Operator, and you don’t use 
a task number. 


If you find you’re unable to sign on but you are 
able to contact the APL system (as would be evi- 
dent if you’re able to receive a message such as 
ALREADY SIGNED ON or NUMBER NOT IN SHARP 
APL SYSTEM or LOCKED OUT), you may still send 
one message to the Operator with the command 
)OPR. But you can’t make any further entry until 
the Operator replies. 


Delivering your message: While the person to 
whom you’re sending the message has the key- 
board open to receive input, your message can’t be 
delivered. It is delayed until after the next time 


the recipient presses RETURN. During that in- 
terval, your keyboard remains locked. If you get 
tired of waiting, you can press BREAK or ATTN. 
The system then abandons your message and sends 
you the report MESSAGE LOST. 


When it dispatches your message to the recipient’s 
terminal, the system sends you the confirmation 
SENT. 


Undeliverable messages: If you address a mes- 
sage to a task that’s not now signed on, the system 
reports SIGNED OFF and abandons your message. 
If the task to which you address the message is 
not a T-task, or is a T-task at which the user has 
elected )KEYB NOMSG, the system sends you the 
report INCOMMUNICADO and abandons your mes- 
sage. 


What the recipient gets: At the recipient’s ter- 
minal, the system displays your task number, fol- 
lowed by the character R if your message expects 
a reply (see below), followed by a colon and a 
space, and then by the text that you typed. 


Since messages are not subject to DPW, there is 
some risk that your message won’t fit into the 
display area of the recipient’s terminal. If the re- 
cipient presses BREAK or ATTN while the sys- 
tem is displaying your message, the display is can- 
celled. However, you won’t know that; the confir- 
mation SENT means that the message was dis- 
patched, but not necessarily that it was received 
in full. 


Message to which a reply is expected: If you 
expect the recipient of your message to send you 
a message in reply, it’s advisable to leave your 
terminal in a condition ready to receive the reply. 
Notice that the reply can’t be delivered while your 
keyboard is open for input. For this reason, fol- 
lowing a message sent with the command )MSG, 
the system leaves your keyboard locked until you 
receive a message. If you get tired of waiting for 


a reply, you can unlock the keyboard yourself by 
pressing BREAK or ATTN. 


When you don’t expect a reply, send your message 
with the command )MSGW rather than )MSG. The 
N stands for “no reply.” When you do that, the 


recipient doesn’t see the character R following your 
task number, and your terminal is unlocked as 
soon as your message is sent. 


)OFF [HOLD] [:password] 
)CONTINUE [HOLD] [:password] 


Either )OFF or )CONTINUE terminates a T-task. 
If you use )OFF, the system simply discards the 
contents of the active workspace. But if you use 
)CONTINUE, the contents of the active workspace 
is saved under the name CONTINUE and the next 
time you sign on, it is automatically reloaded. 


Whenever a T-task is terminated without an ex- 
plicit command )OFF or )CONTINUE (for exam- 
ple, following [BOUNCE or following a communi- 
cations failure or a system failure), the system 
automatically executes a )CONTINUE on your be- 
half. 


Effect: The task is terminated. The system dis- 
plays a message showing the task number, the 
time and date. (The I.P. Sharp Toronto system 
displays those in coordinated universal time.) Fol- 
lowing the time, the display shows the first three 
letters of the account name. 


Following that, the system displays billing infor- 
mation for the task just terminated, and cumula- 
tively for T-tasks since the last billing. This dis- 
play shows connect time in hours, minutes, and 
seconds, CPU time in units, and characters trans- 
mitted and received in thousands. 


Effect of saving CONTINUE: If you use the com- 
mand )CONTINUE to terminate the session, or if 
the system uses it on your behalf following a 
DOBOUNCE or following a communications failure or 
a system failure, the following things happen: 


1. Your active workspace is saved under the name 
CONTINUE. The active workspace is saved and is 
given that name regardless of the name it had 
when )CONTINUE was executed. The newly saved 
CONTINUE replaces any earlier workspace saved 
with that name. 


2. The system makes a note of the fact that the 
session was terminated with )CONTINUE. At your 
next sign-on, it will automatically load 
CONTINUE as soon as you sign on. 
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Security of CONTINUE workspace: You can’t 
specify a workspace password when you sign off 
with )CONTINUE (and of course there’s no way 
to specifiy one when your task is terminated with- 
out a sign-off). Therefore, the system has the fol- 
lowing rules that apply only to a saved workspace 
named CONTINUE: 


1. You can always load CONTINUE from your own 
library without a password. 


2. To any other user, your workspace called 
CONTINUE always appears to be locked. The lock 
is the same as your sign-on password. 


Watch out: At any time, a communications fail- 
ure or a system failure might occur, and if it did, 
would cause the system to save CONTINUE. That 
would have the effect of replacing any earlier 
CONTINUE workspace. For that reason, you 
shouldn’t use CONTINUE for anything other than 
emergency storage from the end of one work ses- 
sion to the beginning of the next. 


Effect of HOLD: If you terminate your task using 
)OFF HOLD or )CONTINUE HOLD, the system 
holds the communications line for a few seconds 
to receive a new sign-on. If you are using dial-up 
equipment, this means that someone else can start 
a work session without having to redial. 


If you don’t use HOLD, the system disconnects dial- 
up equipment. 


Setting your password: To the right of )OFF 
or )CONTINUE (and to the right of HOLD if you 
use it), you may write a colon. That has the effect 
of setting the password you must supply at subse- 
quent sign-ons. The new password is the word 
that appears to the right of the colon. 


A password may be any sequence of 1 to 8 alpha- 
betic or numeric characters. If you supply a pass- 
word having more than eight characters, the sys- 
tem considers only the first eight. 


A password should be a sequence of characters 
that you find easy to remember but which are 
obscure or meaningless to anyone else. A string of 
characters or numbers that has a private meaning 
to you, but not to others, is appropriate. Your own 
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initials, the initials of the company you work for, 
or your sweetheart’s first name are particularly 
inappropriate passwords. 


Before resetting your password, use the command 
)BLOT so that it is impossible to read the new 
password when you enter it. 


)PORT aaa|nnnnnnn 


This command helps you to locate the port and 
task number of another user. It’s usually used to 
find the task number so that you can address a 
message using the )MSG command. 


Following the name of the command, you write 
either the account number of the user, or the first 
three letters of the account name. 


If you use the account number and that account 
is signed on, the system reports all tasks running 
under that account. If you use the first three letters 
of the account name, the system reports that infor- 
mation for all accounts whose names start with 
those three letters and which are currently signed 
on. 


The report the system displays shows (for as 
many tasks as match the number or letters you’ve 


supplied) the following three fields: 


1. Port number. The last three digits refer to indi- 
vidual ports. On the I.P. Sharp Toronto system, 
the two high-order digits are the number of the 
node in the SHARP APL communications net- 
work at which the port is located. For example, 
a value of 79007 means port 007 at node 79. 


2. First three letters of the account name. This 
short form is deliberately chosen to provide confir- 
mation when you’re already familiar with the full 
account name, without disclosing the full name 
when you’re not. 


3. Task number. Only the task number is relevant 
in addressing a message with )MSG or )MSGN. 


)RESET Reset state indicator 


Executing this command completely clears the 
state indicator. Execution of all functions on the 
State indicator is aborted. 


By contrast, the statement consisting solely of the 
right arrow + (the so-called “naked branch”) 
abandons execution of the most recent statement 
entered from the keyboard or resulting from the 
execution of ZX. That has the effect of removing 
the top row of the state indicator and any subse- 
quent rows down to (but not including) the next 
row marked with an asterisk. 


)SAVE [[libno] wsname [:password] ] 


This command saves a duplicate of the active 
workspace. It has no effect on the active workspace 
itself, except that, under some circumstances, it 
changes the current name of the active workspace. 


There are two ways to use the command: with and 
without an explicit indication of the name that the 
saved workspace is to have. 


In carrying out the command, the system refers to 
two items stored within the active workspace: 


1. The current name of the workspace. 


You can display the current name with 
2 [WS 1, or by the command )WSID. 


2. The current password of the workspace. 


If a password exists, it was set when the work- 
space was saved. There’s no way to display the 
password. If you’ve succeeded in loading the work- 
space, or if you’ve reset the password since then, 
presumably you know what it is. 


Using )SAVE without a workspace name: 
When you use the command without a workspace 
name (that is, simply )SAVE), the system assumes 
that you want the active workspace to be saved 
under the name that it currently has, and with 
whatever password it currently has. 


If the active workspace started out as a clear work- 
space, and has not yet been either saved or named, 
it doesn’t have a current name. The system rejects 
the command )SAVE with the message NOT 
SAVED, THIS WS IS CLEAR WS. 


If the active workspace does have a current name, 
the effect of )SAVE is the same as if you’d included 
the current name explicitly as part of the com- 
mand, including both the library number and the 
workspace name. 


Using )SAVE with an explicit workspace name: 
When you include a workspace name explicitly, 
you may or may not also show a library number. 
If you don’t include a library number, the system 
assumes you mean your own library. 


To decide how to respond to your command, the 
system next checks whether or not the library 
number and workspace name you’ve stated (or 
implied by omitting them) describe an existing 
saved workspace. 


When the name and library number in your com- 
mand match those of a workspace that already 
exists, your command is a request to update that 
saved workspace. That is, you’re requesting the 
system to replace the saved workspace with a du- 
plicate of your active workspace. 


When the name and library number specified by 
your command do not match those of an existing 
saved workspace, your command is a request to 
create a new saved workspace. 


Conditions for saving a new version of an al- 
ready-saved workspace: When the library and 
workspace name stated in the )SAVE command 
match the library number and workspace name of 
an existing saved workspace, the system saves the 
active workspace (and thereby replaces the saved 
workspace) only when both of the following condi- 
tions are met: 


1. The current name and library number of the 
active workspace match the name and library 
number stated in the command. 

This is only relevant when you include the work- 


space name explicitly in the command. 
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If this condition isn’t met, the system rejects your 
command with the message NOT SAVED, THIS 
WS IS, followed by the workspace’s current name. 


2. The saved workspace is one that you saved. 


This condition is relevant only when you’re saving 
into a public library. You can’t ever save into a 
non-existent library, or into the private library of 
another user. 


When both the foregoing conditions are met, the 
system saves the workspace. 


Otherwise, the system rejects your command with 
the message IMPROPER LIBRARY REFERENCE. 


Conditions for creating a new saved workspace: 
When the combination of workspace name and 
library number stated (or implied) in your com- 
mand doesn’t match those of any existing work- 
space, you’re requesting to create a new saved 
workspace. The system accepts that request when 
the following conditions are met: 


1. Your workspace quota is larger than the total 
number of workspaces that you now have saved 
(including both workspaces in your private library 
and those you may have saved in a public library). 


If this condition isn’t met, the system rejects your 
command with the message WS QUOTA USED UP. 


2. The library into which you propose to save 
already exists, and you are authorized to save into 
it. 


This is relevant only if the library number stated 
(or implied) in your command is not your own. 
You can’t ever save into a non-existent library, or 
into the private library of another user. 


Setting the workspace password: When you 
state the workspace name explicitly in the com- 
mand, you may at the same time state a password. 
You do that by including a colon to the right of 
the workspace name. The new password is the set 
of characters that you include to the right of the 
colon. 
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A password may consist of any combination of 
alphabetic or numeric characters. The system 
takes the first eight characters as the password. If 
you supply more than eight, it considers only the 
first eight. 


Effect of saving a workspace: The system saves 
a duplicate of the active workspace, under the 
name and library number stated (or implied) in 
your command. 


The saved workspace contains all functions and all 
variables that were present in the active work- 
space, together with the state indicator. However, 
the saved workspace contains no record of what 
files were tied when it was saved, or what num- 
bers were in use to tie them. 


If your request to save is unsuccessful, there is no 
effect at all on the active workspace. 


If your request to save is successful, the only effect 
on the active workspace is that its current name 
and password become the name and password of 
the saved workspace. 


Following a successful save, the system displays 
the time and date at which the workspace was 
saved. If your command did not explicitly include 
the workspace name, to the right of the date the 
system displays the library number (if it was not 
your own) and the workspace name. 


) SEAL Seal the active workspace 


The ability to seal a workspace offers protection 
against display or dispersal of its contents. The 
command takes immediate effect on the active 
workspace. It remains in effect when the active 
workspace is saved. 


Sealing a workspace has the following effects: 
1. All functions now in the workspace are locked. 


2. No function in the workspace at the time it was 
sealed may be erased. Nor may a name that refers 
to a locked function be given a new meaning as 
a consequence of PDEF. 


3. The command )COPY into a sealed workspace 
is treated as if it were )PCOPY and therefore, can- 
not replace any existing global object, regardless 
of whether it was or was not included in the work- 
space at the time it was sealed. 


4. No locked function can be copied from the 
saved duplicate of a sealed workspace. 


Watch out: It remains possible to define a new 
function in a sealed workspace (provided its name 
doesn’t conflict with the name of an existing global 
object). The new function may localize names, and 
there is no restriction on their use. This means 
that the new function may invoke a sealed function 
in a context in which global names to which the 
sealed function refers are shadowed. To assure se- 
curity of your sealed workspace, it is prudent to 
write the definition of any function which is sensi- 
tive and which uses global names, in such a way 
that it verifies the context in which it is invoked 
before it does any further work. 


The command )SEAL is effective only when the 
state indicator is empty. If there’s a suspended 
function on the state indicator, the system displays 
the state indicator and does not seal the workspace. 


Watch out: Sealing a workspace is irreversible. 
You not only prevent others from tampering with 
your workspace, you also prevent yourself from 
making revisions to it. It’s therefore advisable to 
keep somewhere else, an unsealed version of your 
sealed workspace. 


)SI[V] State indicator; 
State indicator with namelist 


Either form of this command causes the system to 
display the state indicator. That is a list of all 
functions whose execution has been started but not 
completed. 


The list shows the functions in the order in which 
execution was started, with the most recent at the 
top. To the right of each function name, there 
appears (in brackets) the number of the current 
line in that function. If execution of that line has 
been suspended, to the right of the line number 
the system shows an asterisk. 


For a line without an asterisk, the number that’s 
shown is the number of the line now active. When 
the system completes execution of the function 
which appears above it in the state indicator, con- 
trol will return to that line. 


For a function marked with an asterisk, the line 
number shown is the number of the line next to 
be executed if execution is resumed in sequence. 


The system function 2 [WS 2 returns a matrix 
identical in appearance to the display produced by 
)SI. 


Namelist: If you use the form )SIV rather than 
)SI, the system displays the state indicator in the 
same way as before, but to the right of each func- 
tion lists all names localized by that function. The 
list includes the result and arguments of the func- 
tion, all labels within its definition, and all addi- 
tional names localized in the function’s header. 


)SYMBOLS [nnn] Symbol table size 
This command either sets or reports the size of the 
symbol table. 


Each workspace contains within it a symbol table. 
The symbol table serves as a dictionary for trans- 
lating between the internal forms in which names 
are stored in the workspace, and the characters 
used to represent a name during entry and display. 


The symbol table contains an entry for every name 
used in the workspace. That includes the name of 
every global object, together with all the names 
appearing within the definition of any defined 
function existing in the workspace. 


The symbol table does not need entries for the 
names used within a package until those objects 
are defined, and exist outside the package. That’s 
because each package contains within it a symbol 
table of its own. 


The symbol table occupies a fixed area within the 
workspace. In a clear workspace, it has space for 
256 distinct names. As you use a workspace, more 
and more entries may be required. 
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It may happen that when the system attempts to 
process a new name, it finds there is no room left 
in the symbol table. When that happens, you need 
to use the command )SYMBOLS to allow more 
space for the table. 


Report of size: When you use the command 
)SYMBOLS with no number to the right of it, the 
system reports the current maximum capacity of 
the symbol table. The same information is also 
supplied as the seventh element of the result of 
2 WS 3. 


The command does not tell you how many of those 
possible symbols are in fact in use, but that infor- 
mation can be obtained as the eighth element of 
the result of 2 (WS 3. Neither of those tells you 
how many symbols are actually needed. 


Resizing the symbol table: When you use the 
command )SYMBOLS nnn (supplying some num- 
ber for nnn), the system does the following: 


1. Counts how many of the current symbol table 
entries are in fact needed to represent all names 
referred to in the workspace. 


If the number of needed entries is greater than the 
number nnn you’ve indicated, the system rejects 
your command with the message 
SYMBOL TABLE FULL. 


2. Rebuilds the symbol table with the capacity 
you've indicated. The new symbol table contains 
only the currently used symbols. 


)TERM [termtype] Terminal type 

The manufacturers of terminals have produced a 
wide variety of makes and models usable with 
SHARP APL. These can be divided into broad 
classes by the encoding and the transmission speed 
they use. Beyond that, terminals differ in other 
ways. The command )TERM permits you to indi- 
cate which of several recognized terminals you are 
using. This won’t fundamentally affect the output 
you receive, but it does permit the system to make 
more accurate allowance for peculiarities of certain 
terminals. 
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The most important use of the command is to 
assist the system in calculating precisely how much 
delay is required between certain transmissions. 
For example, when the cursor is now at position 
100, and the next character to be displayed will 
be at position 1 on the next line, how much time 
should the system allow for the journey? This re- 
quires no perceptible delay in certain video display 
units, but a considerable interval in those that 
must move a typehead over that distance. 


As terminals with different characteristics come 
into use, SHARP APL from time to time extends 
the number of terminals the system recognizes. 


Reporting current terminal type: When you 
use the command )7ERM with nothing after it, the 
system reports the current terminal type. 


Setting the terminal type: When you use the 
command )TERM followed by one of the recognized 
terminal types, the system adjusts output to your 
terminal accordingly. 


The principal types for which distinct conventions 
now exist are as follows: 


ASCII 
IBM2741 


TY33 


The system automatically assigns you to one of 
these three when you sign on (by inferring which 
type is appropriate from characteristics of the sign- 
on transmission). The burgeoning of new models 
of terminals in the last few years has caused a 
greater variety of conventions and operating char- 
acteristics. From time to time, special optimiza- 
tions of output control are prepared for some of 
these. A list of those currently supported, and the 
corresponding abbreviation termtype to be used 
with the command )TERM, can be found in the 
workspace 5 TERM; the list also appears in each 
update of the SHARP APL Reference Card (an 
edition of which is reproduced as an Appendix to 
this manual). 


If after consulting that list, you don’t find mention 
of your terminal, in some cases you may get satis- 
factory results from a terminal whose transmission 
characteristics are similar. For example, in gener- 
al, cathode-ray tube terminals do not require idles 
while repositioning the cursor. 


)WSID [[libno] wsname [:password] ] 
Workspace identification 


You can use this command to report or to set the 
current workspace name and library number of 
the active workspace. 


Report: If you use )WSID with nothing to the 
right of it, the system reports the current name of 
the active workspace. If the library number of the 
active workspace is not your own, it shows the 
library number to the left of the workspace name. 


The system does not report the password of the 
active workspace. 


Setting the workspace identification: You may 
use the command )WSID, followed by a workspace 
name, to set the current name of the active work- 
space. You may also include before the workspace 
name a library number, and after it (separated 
from it by a colon) a password. 


If you specify a workspace name but not a library 
number, the system assumes that to mean your 
own library number. 


If you specify a workspace name but don’t use a 
colon, the system assumes that the current pass- 
word remains unchanged. 


Effect: The system resets the library number, 
workspace name, and/or the password of the ac- 
tive workspace accordingly. It does not inspect the 
number or the name that you assign. Their validi- 
ty is checked only if you attempt to save the active 


workspace. 
$ 
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Chapter 34: 


ERROR MESSAGES 
AND 
TROUBLE REPORTS 





When for some reason work can’t proceed, the 
system may display a message to indicate what has 
happened. This chapter describes what the various 
messages mean and the circumstances that may 
have produced them, and in some cases suggests 
what remedial action you may be able to take. 


Sources of messages and trouble reports 


Messages originate in different parts of the system. 
They can be roughly classified according to where 
they are emitted, as follows: 


1. Communications network or transmission 
control: Certain mesages that you may receive 
at a terminal originate not in the APL system 
itself, but in the SHARP APL communications 
network or the transmission control devices that 
the system uses. They are not sent by APL; in 
fact, they may mean that it is impossible to com- 
municate with the APL system. 


2. The host operating system: If you’re using 
SHARP APL through the I.P. Sharp Toronto 
Data Centre, you won’t see any messages in this 
category. But where SHARP APL is run as one 
of many jobs under the general supervision of an 
operating system (the “host”), there may be cir- 
cumstances under which the host system, rather 
than APL, will send you a message. These depend 
on what the host system is, and they aren’t listed 
in this manual. 


3. Input processor: The APL system constructs 
an input line from the signals it receives from your 
terminal. When it receives an unacceptable trans- 
mission, it may send a message indicating that 
there’s trouble. That entire sequence may take 
place without involving the APL interpreter or 
your workspace. 
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4. Trouble reports regarding system com- 
mands: A trouble report describes a problem en- 
countered in attempting to carry out a system com- 
mand or involving the V (“del”) function editor. 
Since those can be used only from the keyboard, 
the corresponding messages can occur only during 
a T-task. There is no way to correct a command, 
once it has been entered, other than to enter it over 
again (correctly!). 


5. Error or interrupt messages from the APL 
interpreter: Each of these is caused by an event 
detected by the APL interpreter. The event is ei- 
ther an error in a line being executed (either a 
line within a defined function or a line entered 
from the keyboard for immediate execution), or an 
interrupt signalled from outside the workspace 
(usually, from the terminal) while a line is being 
executed. Some (but not all) errors or interrupts 
can be intercepted by an appropriate setting of 
OTRAP, and are said to be “trappable.” 


Trappable errors and interrupts: Each time a 
trappable event occurs, the system sets a new value 
for the system variable DER (event report). If the 
event is not trapped, execution halts. If the task 
is an N-task or B-task, the task is ended and its 
active workspace is saved. If the task is a T-task, 
the system displays a message. The message is 
identical to the content of QER, except that DER 
also contains an event number while the display 
does not. Procedures for handling trappable events 
are discussed in the chapter entitled “Automatic 
Trapping of Errors and Interrupts.” 


Following an untrapped error or interrupt, it may 
be possible to take corrective action. If the message 
is in response to an entry from the keyboard, you 
may be able to correct the entry using the line 
editor; line editing is discussed in the chapter on 
“Modes of Interaction at a Terminal.” If the mes- 
sage was in response to something that happened 
during execution of a defined function, it may be 
possible to take corrective action and then resume 
execution. 


Form of error messages: When the APL inter- 
preter encounters an untrapped error or interrupt, 
it sends you a three-part message. The first is a 
general description of the type of problem, (for 
example, SYNTAX ERROR or VALUE ERROR, etc.). 


Then it shows you the line that contains the error. 
If the line is a line within a defined function, it 
shows also the name of the function and the num- 
ber of the line on which it is found. (If it’s a 
locked function, the system shows the function 
name and statement number, but not what is on 
the line.) 


Below that, the system displays a caret. The caret 
shows the part of the line on which the system was 
working when it discovered the error. For some 
errors, the system can point quite precisely at 
what’s wrong. For others, it’s harder to point to 
“whats wrong.” For example, if the problem is 
that you omitted a parenthesis, it’s hard for the 
system to know where you omitted it, so instead 
it shows where it was working when it found they 
didn’t match. 


What has been executed when an error is re- 
ported: When the system displays a line of APL 
marked with a caret, part of the line may have 
been executed already, before the system discov- 
ered the error. In general, you can tell what has 
been executed by the position of the caret. But it 
is prudent to check further, since the caret’s posi- 
tion is subject to change. An approximate rule is: 


1. Within a line containing diamonds, statements 
to the right of the caret have not yet been exe- 
cuted. 


2. Within the statement to which the caret is 
pointing, functions to the right of the caret have 
been executed. 


If the statements or functions that have already 
been executed produce some lasting change (for 
example, by respecifying the value of a variable 
or of a file component), you may have to make 
allowance for that before you re-execute the line. 


Point of view in describing an error: Most 
errors arise because you didn’t state what you 
wanted in a way acceptable to the system. From 
your point of view, the most helpful message the 
system could give would be one that tells you what 
you should have done. But what you should have 
done can be defined only by referring to what you 
have in mind. The computer has no way of know- 
ing that. So whenever it encounters a problem, the 
system describes what was wrong from its point 
of view. The definitions that follow elaborate on 


ERROR MESSAGES AND TROUBLE REPORTS 278 


what the various error messages mean to the sys- 
tem, and in some cases suggest what may have 
brought them about, and what corrective action 
you may be able to take. 


Descriptions of error messages 
and trouble reports 


APL DEFINITELY HUNG 
APL PROBABLY HUNG 


The transmission control has detected that the 
APL system is no longer responding, probably in- 
dicating a system failure. This message is usually 
transitory; the operations staff will be aware of the 
condition, and will attempt corrective action. 


APL NOT AVAILABLE 


The operations staff is in the process of starting 
APL, but it is not yet ready to accept sign-ons. 
This condition should not last more than a few 
minutes. 


APL PROBABLY DOWN 


Although you’re in contact with the transmission 
control, it is not in touch with the APL system, 
and it appears that the APL system is not run- 
ning. This may be because you've called at a time 
outside norma! hours, or because the system is not 
running for some other reason. 


ATTENTION 


This message is not displayed. However, it is the 
error description used in (ER when execution is 
halted by a single use of ATTN or BREAK. Exe- 
cution halts after completion of work on the cur- 
rent line. If ATTENTION occurred during work on 
a defined function, DER (and DZC) show the num- 
ber of the line next to be executed. (Trappable as 
event 1002.) 


~~ 


AWAITING FUNCTION FOUR 


This message is sent by the transmission control 
unit during one of the phases of system start-up. 
It probably means that the operations staff is cur- 
rently starting the system, so it is likely that this 
condition will be transitory. 


CHAR ERROR 


The input processor has detected an overstrike that 
does not form a valid APL character. It echoes to 
you the characters it has received up to the invalid 
character, and waits for you to retransmit the re- 
mainder. Note that this. error is detected before 
your entry reaches the APL interpreter, and can- 
not be trapped. 


CLEAR WS 


Following a system error, and also following an 
interrupt in a workspace in which CLEAROUT has 
been set, the system in effect executes the com- 
mand )CLEAR on your behalf. It does this follow- 
ing a system error because the workspace has been 
damaged and may contain spurious data that could 
be dangerous to the system. (Not trappable. ) 


DEFN ERROR 


You have invoked the V function editor improper- 
ly. The impropriety might be any of the following: 


1. While in immediate execution mode, you’ve en- 
tered a line which starts with [ (and thus looks 
like a line number), or you’ve entered a line that 
starts with V (and thus looks like a request to 
enter definition mode), but you haven’t provided 
a valid function header. Following the initial V, 
you need: 


a. For a function that already exists, just the 
name of the function. 


b. For a new function, the name can’t be a 
name that’s already in use as the name of a global 
variable or function. 
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c. For a new function (but not for an existing 
function), you should write a complete header, 
including names for the result, arguments, and 
local names. 


2. While in execution mode, you’ve tried to open 
the definition of a locked function. 


3. While editing a function, you’ve supplied a line 
number starting with [ but not followed by a 
plausible line number and a closing J. 


4. You’ve tried to enter definition mode while an- 
swering a request for evaluated input. 


DEFN ERROR is not trappable (but note that an 
error in the use of DFD or DFX may be trappable 
as a DOMAIN ERROR, or by considering the result 
of OFX). 


DOMAIN ERROR 


You’ve invoked a function, but the argument you 
have supplied with it is outside the function’s do- 
main. Common examples: you’ve tried to divide by 
zero, or to catenate numbers and characters, or 
you’ve supplied a fractional argument to a func- 
tion defined only on integers. Consult the descrip- 
tion of the function in question for the criteria for 
an acceptable argument. (Trappable as event 11.) 


FILE ACCESS ERROR 


You’ve tried to tie a file to which you have not 
been given access, or to tie it without the correct 
passnumber, or, having tied it, to use with it a 
function for which the file’s access matrix doesn’t 
give you authorization. The system keeps a log of 
file access errors. (Trappable as event 19.) 


FILE BACKUP INTERRUPT 


You’ve signalled an interrupt (two successive uses 
of ATTN or BREAK) and have interrupted a file 
operation which is delayed during a system file 
back-up. File back-ups don’t take very long, so the 
usual remedy is to try again in a few minutes. 
(Trappable as event 1007.) 


FILE COMPONENT DAMAGED 


You’ve attempted to read a file component which 
is unreadable because of an inconsistent file system 
internal directory following a system crash. 
There’s no immediate remedy. Notify the system 
Operator or your SHARP APL representative for 
assistance. (Trappable as event 38.) 


FILE DAMAGED 


The file you’re trying to use has been marked 
“damaged” in the directory that the system main- 
tains. A file is marked damaged if the file crash 
recovery program cannot successfully recover the 
file after a system crash. In addition, a system 
programmer can mark a file as damaged if re- 
quired. While the directory is damaged, the only 
functions you can use with it are DTIE, OSTIE, 
OERASE, and QUNTIE. Any other function is re- 
jected with the message FILE DAMAGED. A dam- 
aged file is not archived to magnetic tape, and will 
be lost following a full dump full restore (usually 
done each weekend). You can ask to have the 
previous version of the file restored from archive. 
Notify the system Operator or your SHARP APL 
representative for assistance. (Trappable as event 
23.) 


FILE FULL 


You’ve attempted to append a new component to 
a file whose current size already exceeds the num- 
ber of bytes reserved. Remedy: resize the file. 
(Trappable as event 21.) 


Note: you might expect that replacing some of the 
existing components with data that requires less 
space would decrease the total storage of the file. 
While that is true in the long run, it does not 
always reduce the total size at once. That’s be- 
cause the physical storage freed by doing that may 
not be available to the new components you want 
to append until after the weekly file maintenance 
has been performed. 
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FILE INDEX ERROR 


You’ve used DREAD, OREPLACE, ORDCI, or DDROP 
with an argument that refers to a non-existent file 
component. (Trappable as event 20.) 


FILE INTERRUPT 


You’ve signalled an interrupt (two successive uses 
of ATTN or BREAK) and have interrupted a file 
operation. Remedy: when ready, retry the opera- 
tion. 


Watch out: If the interrupted file operation is 
embedded in a long line, other parts of the line 
may have been executed, and may make it impru- 
dent to re-execute the line from the beginning. 
(Trappable as event 1006.) 


FILE NAME ERROR 


The left argument of OTIE, OSTIE or OCREATE 
is not a valid name, or, where the function must 
refer to an existing file, not the name of an exist- 
ing file. (Trappable as event 22.) 


FILE QUOTA USED UP 


You have requested creation of a new file, but the 
number of files you own is already equal to your 
quota. Remedy: erase an unwanted file, or ask the 
system Operator for a larger quota. (Trappable 
as event 32.) 


FILE RESERVATION ERROR 


You have requested space for a file (either by 
resizing an existing file or by creating a new one) 
in a way that would make the sum of the reserva- 
tions for all your files greater than your file reser- 
vation quota. Remedy: first erase or resize some 
of your existing files, and/or ask the system Oper- 
ator for an increased file reservation limit. 


(Trappable as event 33.) 


FILE SYSTEM ERROR 


There is something seriously wrong with the file 
system. Report the occurrence to the system Oper- 
ator so that corrective action can be taken. 


(Trappable as event 26.) 


FILE SYSTEM NO SPACE 


You have requested to reserve space, or to append 
records, in a way that is within your limits, but 
which the file system is unable to honour because 
it has insufficient available space. Notify the sys- 
tem Operator so that corrective action can be 
taken. (Trappable as event 34.) 


FILE SYSTEM NOT AVAILABLE 


You have used a file function other than QAVAIL 
at a time when, although APL is running, the file 
system is not. This condition may arise during the 
first few moments following initial availability of 
the system. Remedy: wait a few minutes and try 
again. (Trappable as event 28.) 


FILE SYSTEM TIE CAPACITY EXHAUSTED 


The system now has tied its maximum number of 
distinct files. The situation may be temporary, but 
you should bring it to the attention of the system 
Operator so that steps can be taken to decrease the 
likelihood of a recurrence. 


FILE TIE ERROR 


You’ve used a tie-number as if it were tied when 
in fact it is not, or as if it were free to be tied 
when in fact it is already tied. (Trappable as event 
18.) 


FILE TIE QUOTA USED UP 


The system imposes a maximum on the number 
of files that one task may tie at one time. The limit 
is currently twenty. You’ve attempted to tie a file 
in excess of that limit. (Trappable as event 31.) 
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FILE TIED 


You’ve attempted to tie a file that is exclusively 
tied by another task. There’s no immediate reme- 
dy, other than to wait. You may want to arrange 
with other users of the file to avoid exclusive ties, 
or amend the access matrix to prohibit them. 
(Trappable as event 24.) 


FILES UNTIED 


While disconnecting you from the system (as a 
result of a sign-off or bounce), all files you had 
tied have been untied. 


FORMAT ERROR 


You have supplied an invalid argument to DFMT. 
The system displays the portion of the left argu- 
ment of QF MT which it was attempting to interpret. 
(Trappable as event 7.) 


IDENTIFICATION IN USE 


You have attempted to use [SVQ or dyadic DSVO 
at a time when another task is using shared varia- 
bles, and already has established the clone ID that 
you are now using. Remedy: set a unique clone 
ID. (Trappable as event 77.) 


IMPROPER LIBRARY REFERENCE 


You have attempted to use the command )LIB to 
list the contents of someone else’s private library, 
or to use )SAVE to save into a private library other 
than your own, or to resave a public library work- 
space of which you are not the owner. (Not trap- 
pable.) 


INCOMMUNICADO 


You have used the command )MSG or )MSGN to 
address a message to a task which is unable to 
receive a message, either because it is not a T-task 
or because its owner has executed )KEYB NOMSG. 
(Not trappable.) 


INCORRECT COMMAND 


You have typed an entry which begins with ), but 
which the system does not recognize as an APL 
command, or in a way that violates the required 
syntax for that command. (Not trappable.) 


INCORRECT SIGN-ON: .: 


The first transmission the system has received 
from you contains characters that could not occur 
in a valid sign-on. This may be simply because 
you mistyped something. It may also arise from 
an inappropriate or malfunctioning terminal, or 
from an incorrect setting of switches on the termi- 
nal (for example, setting a terminal to transmit 
everything in upper-case). The APL system re- 
quires an APL colon as part of the sign-on. If 
you’re using a terminal which does not have an 
APL character set, you may be transmitting the 
wrong character for colon; the system ends its mes- 
sage with two instances of the character it expects 
to separate your account number from your pass- 
word. 


INDEX ERROR 


Within the brackets that delimit an index, you 
have supplied a value that is not a valid index for 
the object being indexed. (Trappable as event 3.) 


INPUT INTERRUPT 


You have interrupted input from the terminal (in 
response to Q or M) with O BACKSPACE y 
BACKSPACE 7. (Trappable as event 1004.) 


INTERFACE CAPACITY EXCEEDED 


You have attempted to assign to a shared variable 
a value which requires more storage space than 
the system’s shared variable processor can accept. 
(Trappable as event 74.) 
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INTERFACE QUOTA EXHAUSTED 


You have attempted to offer to share more varia- 
bles at one time than the SHARP APL system 
allows (at present, 100). Remedy: retract some. 
(Trappable as event 72.) 


INTERRUPT 


The system has received an interrupt signal (two 
successive uses of ATTN or BREAK). It has cut 
short execution of the line it was executing. 


When a function is executing, a strong interrupt 
is signalled by two successive uses of BREAK or 
ATTN. During input, a strong interrupt is signal- 
led by keying the sequence O BACKSPACE JU 
BACKSPACE 7T. 


Watch out: Part of the line may have been exe- 
cuted. An instruction to store data that occurs 
within this statement and to the right of the caret 
may have been carried out already. That includes 
assigning a new value to a variable or storing 
something in a file. If you re-execute the line, 
notice that that storage (variable, or file compo- 
nent) may already have received a new value. 


The system discriminates several different inter- 
rupts, according to the activity that was interrupt- 
ed: 


1004 Interrupt during O or M input 

1005 Interrupt while awaiting a shared variable 
access 

1006 Interrupt during a file operation 

1007 Interrupt during file back-up 

1003 An interrupt during execution, but not 
1005, 1006, or 1007 


LENGTH ERROR 

You have used a dyadic function which requires 
its arguments to match in length, but your argu- 
ments do not match along the axes where that is 
required. (Trappable as event 5.) 

LIBRARY TABLE FULL 


The system’s table of workspace names has no 
room to accommodate the name of the workspace 


_— 


you propose to save. Notify the system Operator 
so that corrective action can be taken. (Not trap- 
pable. ) 


LINES DOWN 


This message is sent by a minicomputer in the 
Sharp communications network, somewhere be- 
tween you and the central computer. The mini has 
lost contact with the central transmission control, 
probably because of a failure in a telephone circuit 
linking nodes of the network. When it notices that 
you’re no longer connected, the APL system exe- 
cutes )CONTINUE on your behalf, so your work is 
saved. Note that LINES DOWN does not disconnect 
your local telephone link. A communications fail- 
ure is sometimes only momentary, so it may be 
possible to sign on again almost immediately. 


MESSAGE LOST 


The message you entered with the command 
)MSG or )OPR has not been sent because the sys- 
tem received an attention signal from your termi- 
nal after you sent the message but before it was 
dispatched. 


NO SHARES 


You have used a shared variable function at a time 
when the system’s shared variable processor is not 
running. This is an unusual state of affairs. It may 
be sufficient to wait briefly. Otherwise, consult the 
system Operator or your SHARP APL represent- 
ative. (Trappable as event 73.) 


NO SPACE 


The system is unable to save the workspace as you 
requested because it lacks the necessary space. No- 
tify the system Operator so that corrective action 
can be taken. (Not trappable. ) 


NONCE ERROR 


The expression you have used appears valid, but 
the interpreter is not at present (i.e. for the nonce) 
equipped to execute it. This message may be en- 
countered if you use a function that has been pro- 
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PPAR 


real 


posed (and which the system recognizes) but 
whose implementation is not yet released. (Trap- 
pable as event 16.) 


NOT COPIED: 


The listed items have not been copied either be- 
cause their names conflict with protected names in 
your active workspace, or because the workspace 
you're copying from is sealed. A name in your 
active workspace may be protected because the ac- 
tive workspace is sealed; because it is the name of 
an active function; or because the command you 
used was )PCOPY rather than )COPY. 


NOT ERASED: 


The listed items have not been erased by your 
)ERASE command. An object is not erased if it’s 
a function in a sealed workspace, or an active 
function. 


NOT FOUND: 


The listed names are not the names of global ob- 
jects in the active workspace (if you tried to erase 
them) or in the source workspace (if you tried to 
copy them). Note that these commands apply only 
to global objects. 


NOT SAVED, THIS WS IS . 


You have used the command )SAVE in a work- 
space that has no current name, or the command 
)SAVE wsname when the workspace name you 
have provided matches the name of an existing 
saved workspace, but does not match the current 
name of the active workspace. (Not trappable.) 


NOT WITH OPEN DEFINITION 
While in function definition mode, you have tried 


to use a system command other than )nnn. (Not 


trappable. ) 


NUMBER IN USE 


Your attempt to sign on a T-task is unacceptable 
because a T-task on your account number is al- 


ready signed on. This may arise because you sim- 
ply forgot to sign off. Sometimes it happens when 
you turn off power to a terminal, but instead of 
signing you off, the system simply sees you as 
inactive. If you are unable to sign off, you may 
be able to get another user to start an N-task on 
your account (which would require revealing your 
password) and then have the N-task bounce the 
T-task. Alternatively, you could attempt to contact 
the system Operator by some other means and 
again request the Operator to bounce your T-task. 
Notice that while connected but not signed on, you 
can use the command )OPR to send one message 
to the Operator. 


NUMBER LOCKED OUT OF SHARP APL SYSTEM 


Although the number and password with which 
you've tried to sign on are valid, the account num- 
ber you’ve used has been locked out of the system. 
Consult your SHARP APL representative. (You 
can use )OPR to send one message to the Operator 
even when you’re not signed on.) 


NUMBER NOT IN SHARP APL SYSTEM 


The combination of number and password sup- 
plied in your attempt to sign on is not valid. This 
may be because you have the number wrong, or 
because the password you supplied is not appro- 
priate to that number. The system maintains a log 
of invalid attempts to sign on. 


PATIENCE PLEASE 


The system has not yet been able to terminate a 
T-task on your account number, even though it is 
identified as “bounced.” This may be a transitory 
condition. If it persists, contact the system Opera- 
tor. (Note that you can send one message with the 
command )OPR even when not signed on.) 


PROCESSOR TABLE FULL 


You have used (SVQ or dyadic SVO, which re- 
quires the shared variable processor to create for 
you an entry in its table of processor IDs, but the 
table has no room for a further entry. (This 
should be a transitory problem, so it may be suffi- 
cient to wait briefly and try again. Otherwise, con- 
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sult the system Operator or your SHARP APL 
representative.) (Trappable as event 76.) 


RANK ERROR 


You have used a monadic function whose argu- 
ment is limited to a particular rank with an argu- 
ment of some other rank. Or you have used a 
dyadic function with arguments that do not corre- 
spond in rank when they should. (Trappable as 
event 4.) 


SENT 


The message that you entered with the command 
)MSG or )OPR has been dispatched. For a message 
addressed to the Operator, this guarantees that it 
will appear at the Operator’s terminal. For a mes- 
sage addressed to another user, it indicates only 
that the message was dispatched; the recipient 
might signal attention in a way that would cut 
short its display. 


SI DAMAGE 


You have changed the definition of a suspended 
function in a way that changes its use of names 
(by changing its header or its labels). This makes 
it impossible to resume its execution. Remedy: 
clear the state indicator by executing > as needed, 
or clear the state indicator completely by the com- 
mand )RESET. 


SIGNED OFF 


The task to which you have addressed a message 
is not now signed on. 


Watch out: This may be because the task was 
signed on earlier but has since signed off, but it 
may also arise because you’ve mistyped the task 
number and thereby addressed a message to a task 
that never was signed on. 


SHARE TABLE FULL 


You have offered to share a variable, but the sys- 
tem’s shared variable processor has no room in its 
table of shared variables to accommodate a new 


entry. (This should be a transitory problem, so it 
may be sufficient to wait briefly and try again. 
Otherwise, consult the system Operator or your 
SHARP APL representative.) (Trappable as 
event 75.) 


STOP 


This message is not displayed, but appears in 
DER when execution of a function is halted because 
stop control was set on the line about to be exe- 
cuted. (Trappable as event 1001.) 


SV INTERRUPT 


You have signalled an interrupt (by two successive 
uses of ATTN or BREAK) and have interrupted 
an access of an interlocked shared variable. Reme- 
dy: verify access control (SVC) and shared varia- 
ble state (SVS). If it is appropriate to retry the 
access, re-execute the line. Trying the same access 
again doesn’t constitute a new reference to the 
shared variable, but rather a continuation of the 
previous attempt. (Trappable as event 1005.) 


SWAP ERROR, CLEAR WS 


The system finds (in the course of “swapping” 
your active workspace to auxiliary storage) that 
it is no longer able to read your active workspace. 
It is not possible to recover the active workspace 
following a swap error. After a swap error, the 
preceding value of the session variables QSP and 
DHT is lost, and in the ensuing clear workspace, 
each is an empty vector. Notify the system Opera- 
tor of the problem, so that action can be taken to 
fix the malfunction. If this error occurs during an 
N-task or B-task, the task is terminated, and 
(ER in its saved workspace indicates event 67; 
however, event 67 is not trappable. 


SYMBOL TABLE FULL 


The line you are trying to execute, or the package 
whose contents you are trying to define, or the 
object you are trying to copy, require the use of 
names for which there is no space in the symbol 
table. Remedy: resize the symbol table by the com- 
mand )SYMBOLS nnn. (When this arises during 
execution of an APL statement, it is trappable as 
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event 15. But when it arises during use of the 
commands )LOAD or )COPY, it is not trappable.) 


SYMBOL TABLE FULL ERROR 


The system has insufficient space in the symbol 
table to prepare a proposed line for execution. 
(Not trappable. ) 


SYNTAX ERROR 


The syntax analyser has detected a statement 
which appears to be in violation of the syntactic 
rules of the language. This could be for any of 
several reasons; for instance: 


1. You have used a function that requires a right 
argument without one. 


2. You have unbalanced parentheses or brackets. 


3. You have juxtaposed two names that appear to 
be the names of variables with no indication of a 
function to be applied to them. If you refer to a 
defined function whose definition is not visible in 
the workspace, the system will usually understand 
that as a reference to two variable names, and 
report a SYNTAX ERROR. (Trappable as event 2.) 


SYSTEM ERROR, CLEAR WS 


The system has encountered an undiagnosed error 
while executing a command or an APL statement 
in your workspace. It displays, at your terminal 
and at the Operator’s terminal, a listing of the 
contents of certain internal registers, as an aid to 
the system personnel in diagnosing the problem. 
Because a damaged workspace is potentially dan- 
gerous to the system, the system thereafter clears 
your workspace. Following a system error, the 
former values of the session variables [ISP and 
DHT are lost, and in the ensuing clear workspace, 
each is an empty vector. 


To help the SHARP APL system personnel in 
locating the source of the trouble, it will be useful 
if you keep a record as exact as possible of what 
you were doing from the preceding )ZOAD or 
)CLEAR to the moment the system error occurred. 


(Not trappable. After it clears the workspace, the 
system sets [JER to report event 68.) 


SYSTEM RESET DETECTED 


The transmission control has detected a fresh start 
at the central computer, implying that the previous 
work session probably ended in a system crash. 
After you receive this message, if all goes well, 
depending on what caused the system crash, it may 
be possible to restart the system. As a step in 
restarting, the system will first attempt to recover 
all workspaces as they were, or, failing that, as 
they were 4 seconds before the crash occurred. 


VALUE ERROR 


You have referred to what appears to be the name 
of a variable which has no visible value, or to the 
result of a function which fails to return a result. 
This might be because the name is shadowed dur- 
ing execution of a function, or because the value 
really doesn’t exist in the workspace. This message 
often arises because you’ve misspelled the name of 
the variable. (Trappable as event 6.) 


WS FULL 


If the system were to execute the function, or to 
copy the requested objects, it would require more 
space than is available in the workspace. When 
you save a workspace containing a shared variable, 
before carrying out the save, the system must 
record the current value of any shared variables. 
If your partner has given them values so large that 
your workspace has no room to accommodate 
them, the system will report WS FULL and will not 
save the workspace unless your task has been 
forced off by a communications failure or a system 
crash. Remedy: sometimes it suffices to erase un- 
wanted objects in the workspace. Alternatively, it 
may be necessary to alter the algorithm so that its 
intermediate storage is not so extensive. (When 
this condition arises as the result of executing an 
APL expression, it is trappable as event 1. But 
WS FULL arising during )COPY or )SAVE is not 
trappable. ) 
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WS FULL ERROR 


The system has insufficient space to set up a pro- 
posed line for execution. (Not trappable. ) 


WS LOCKED 


While referring to a workspace, the password you 
have supplied does not match the actual password 
with which the workspace was saved. This could 
arise either because the workspace requires a pass- 
word but you did not supply the right one, or 
because it has no password and you did supply 
one. If your reference to the workspace occurred 
in an APL expression, (i.e. one that invoked 
OLOAD, DQLOAD, or ORUN), this event is trappable 
as event 45. But if your reference was in a system 
command, it ‘is not trappable. 


WS NOT FOUND 


The workspace you requested cannot be found in 
the library stated (or implied) in your request to 
load or copy a workspace. If your reference to the 
workspace occurred in an APL expression, (i.e. 
one that invoked DLOAD, D@LOAD, or ORUN), this 
event is trappable as event 46. But if your refer- 
ence was in a system command, it is not trappable. 


WS NOT READABLE 


The system is unable to read the saved workspace 
you have requested to load or copy. No immediate 
recovery is likely. Contact the system Operator or 
your SHARP APL representative, to arrange who 
will attempt to recover the workspace, or failing 
that, to restore it from the back-up tapes of saved 
workspaces. (When this happens following a com- 
mand )ZOAD or )COPY, DER is not set. But when 
it happens in response to DLOAD or (JQLOAD, DER 
is set to show event 47, which is trappable.) 


WS QUOTA USED UP 


You have tried to save a workspace, but you al- 
ready have saved your full quota of saved work- 
spaces. (Each user is entitled to have a workspace 
called CONTINUE saved following a system crash, 


bounce, or a communications failure. CONTINUE 
does not count against your quota, and you should 
not use it for regular storage because it could be 
replaced by the active workspace at any future 
crash, bounce, or communications failure.) Reme- 
dy: drop an unneeded workspace, or request a 
larger quota from the system Operator. 


Oxx ERROR 
You’ve used a function which requires a valid 


value of the indicated system variable, but it isn’t 
present. Check the requirements for this system 


variable in the section devoted to it. 
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Appendix. A: APL distinguishes only two types of simple data: 


numbers and characters. 


Internally, the system uses three different formats 
for the representation of numbers. The three inter- 
nal types for numbers are called, respectively, 
Boolean, integer, and floating point. There’s a 
fourth type for characters. 


INTERNAL 
DATA TYPES 


For most purposes, the type of internal storage 
that the system uses for a numeric array is simply 
a matter of the system’s housekeeping, and need 
not concern you at all. The system converts auto- 
matically from one type to another when the need 
arises. 


Storage type affects space requirements: The 
internal type of a numeric array greatly affects the 
amount of space required to store it, and is there- 
fore an important consideration when you’re de- 
signing an application that will store large 
amounts of data. (Stating it the other way, these 
storage types exist because it is possible to make 
large reductions in the space required to store 
numbers if you can be certain in advance that 
none of them will contain fractions, or all of them 
will be confined to the values 0 or 1.) 


There are a few cases in which the internal type 
of the argument affects the speed with which a 
function is executed. For example, for some func- 
tions, Boolean arguments (while requiring much 
less space), are somewhat less efficient in execu- 
tion. 


Internal type is a characteristic of an entire simple 
array. That is, every element of a simple array 
must be stored in the same internal type. The 
internal type must be chosen so that no element 
loses significant information. That means that 
every element must be stored in the format re- 
quired for the most demanding element. If any 
element is a fraction, then they must all be stored 
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in a form capable of representing fractions, even 
if for all the other elements the fractional part is 
all zeros. 


Boolean is used for data confined to the values 
O or 1. It requires only one binary bit per element, 
and so eight elements can be stored in a single byte 
of workspace or file storage. 


Integer representation is used for numbers none 
of which has a fractional part, and all of which 
fall in the range -2*31 through 1+2*31 (that 
is, -2,147,483,648 through 2,147,483,647). Each 
integer element is represented in 32 binary bits, 
of which the first is used for the sign. 


Floating-point format is used to represent any 
number having a fractional part, or any integer 
outside the range representable in the 32-bit inte- 
ger format. Each element is represented by 64 bits, 
of which 56 are used for the fraction, 6 for the 
exponent, and one each for the sign of the number 
and the sign of the exponent. 


Note than any number that can be represented in 
integer format, can also be exactly represented in 
floating-point. Indeed, the range of integers that 
can be exactly represented in floating-point format 
is from -16*14 to 1+16*14 (that is, -72,057- 
594,037,927,940 to 72,057,594,037,927,939, inclu- 


sive). 


Bytes per element by type 
LE E. 


Internal type 


Bytes per element 
noe ý EE 


Boolean 0.125 
Integer 4 
Floating point 8 


Character 
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Storage overhead: In addition to the space re- 
quired for each element, every simple array also 
requires storage to identify its internal type, rank, 
and shape. These require 4x3+r bytes, where r is 
the rank of the array. Storage is allocated in units 
of four bytes, so the total space required is round- 
ed up to a multiple of 4. The number of bytes 
required to store an array (not including the space 
in the symbol table for its name) is returned as 
the result of 4 WS. 


Inferring the internal type of an array: You 
can deduce the type used internally to represent 
an array from the amount of storage it requires. 
For example, the function 7 returns an integer 
from 0 to 5 to describe the internal type of its 
argument: 


V ZT X; DIO 
[1] DI0<0 
[2] e(2=ppOPNAMES X)/'Z<5 © > 1! 
[3] X*«(5xxx/pX)pX 
C4] Z+ 16 20 36 56 24 14 {WS 'X! 


[5] a RETURNS INTERNAL TYPE OF ARGUMENT 
[6] A O=EMPTY 

[7] A 1=BOOLEAN 

[8] a 2=INTEGER 

[9] Aa 3=FLOATING 

[10] a 4=CHARACTER 
[11] a 5=PACKAGE 


Internal type of the result of a function: It’s 
obvious that the internal type resulting from 1^1 
should be Boolean, and that’s what the system 
does. It’s less obvious how the system should rep- 
resent the result of 1x1 (which could be Boolean, 
but, at least at present, is not). Since an entire 
array must be represented in the same type, insert- 
ing a single element of a larger type requires con- 
verting the entire array, and may have significant 
implications for storage. The table that follows is 
intended to assist the programmer who needs to 
verify the internal type of a function’s result. In 
describing the internal type, the table uses the 
function 7, described in the preceding section, and 
the function R to indicate the type required by the 
value of the result. The function R determines 
whether the result is confined to the values 1 and 
0, whether it exceeds the range of representable 
integers, and whether it contains a fraction. 


[1] 
[2] 
[3] 
C4] 
[5] 


Vy 


Vv 


Function 





Z+R X; DCT 
DCT<0 


Zeit+(v/,~Xe 0 1)+v/, (X<-2x31)v(X22*31)VXzLX 


ARETURNS 1 WHEN ARGUMENT ENTIRELY 0 1 


A2 WHEN INTEGER IN RANGE -2x31 TO ~1+2*31 


A3 WHEN FRACTION OR OUTSIDE THAT RANGE 


Internal type of result 
ere 


Type of result 


+Y 
xY 
-Y 
+Y 
*Y 
@Y 
oY 
EY 
|Y 
Ly. 
ry 
LY 
~Y 
2y 
X+Y 
X-Y 
XxY 
X+Y 
XxY 
X1LY 
XTY 
X|Y 
XTY 
XLY 
X@®Y 
X'yY 


T Y 
[/2, TY 
[4252 Y 


Y), R!Y 
R [Y 
R LY 


T-Y 
X), 
X), 
X), 
X), 
X), 
X), (T 
X), (T 
X), T 
X). T 
X), T 


(T 
(T 
(T 
(F 
(T 


PRPRERPP PR ER ww ww 


Appendix A: 


Tolerance during automatic conversion to 
Boolean: The logical functions ~ A v ~ take 
arguments that are confined to values 0 or 1. 
When the internal type of an argument is floating 
point, any of those functions tolerates an argument 
whose value is within about 1 14 of either 0 or 
1. This tolerant conversion is unrelated to compar- 
ison tolerance, and is not affected by OCT. 


Tolerance during automatic conversion to inte- 
ger: A number of functions require one or both 
of their arguments to be integral (for example, the 
left argument of * + >, both arguments of 7, and 
the right argument of 1). Indexing requires inte- 
ger indexes, and the axis operator requires an in- 
tegral axis number (except in the case of lamina- 
tion). 


Where a function is restricted to integer arguments 
but the internal type of the argument is floating- 
point, the system tolerates a fractional value pro- 
vided it is within about 17 13 of an integer. The 
actual value of the tolerance varies somewhat, de- 
pending on the value of the argument. This toler- 
ance is unrelated to comparison tolerance, and is 


not affected by DCT. 
$ 
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During the early stages of the development of the 
SHARP APL file system, all file access was pro- 
vided by a single system keyword FF. Its right 
argument was a numeric vector in which the first 
element selected a particular file function, and the 
remaining elements were interpreted in the same 
way as the right arguments of the various file 
functions in use today. In time, the function FF 
was renamed QFF. The system function (FF is 
now considered obsolete, but is still tolerated. Its 
functions are duplicated by the various file primi- 
tives such as DSTIE, DREPLACE, and so on. How- 
ever, if you run across an old function whose defi- 
nition uses DFF, you can decipher the meaning of 
the argument of DFF from the following defini- 
tions: 


V R FCREATE N 
[1] R OFF 1,N 

V 

V R FTIE N 
[1] R DFF 2,N 


V FUNTIE N 
[1] OFF 3,N 


[1] R DFF 4,N 


V R FERASE N 
[1] R OFF 5,N 


V ReFREAD N 
[1] RFF 6,N 


V R FAPPEND N 
[1] R DFF 7,N 


[1] 


[1] 


[1] 


[1] 


[1] 


[1] 


[1] 


[1] 


[1] 
[2] 
[3] 


[1] 


[1] 


[1] 


[1] 


V 


v 


R FREPLACE N 
R JFF 8,N 


R+FLIB N 
ReOFF 9,N 


ReFSIZE N 
ReutQFF 10,0 


R-FRDCI N 
Re3+QFF 11,N 


FDROP N 
DFF 13,N 


FHOLD N 
OFF 14,N 


R FRENAME N 
R OFF 15,N 


R+FRDAC N 
RFF 16,N 


R FSTAC N3I 
I+(pR)p2 
Il;]«R 

I OFF 17,N 


ReFNUMS 
RFF 18 


R<FPNAMES 
RFF 19 


R FRESIZE N 
R OFF 24,ŅN 


R+FAVAIL 
RFF 25 


dey 
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Appendix C: GROUPS 


In APL\360 and in early versions of SHARP 
APL, groups were used as a way to simplify copy- 
ing several related items from a saved workspace, 
or erasing them in the active workspace. Groups 
are now considered obsolescent, but still exist in 
SHARP APL. Storing or transporting several dis- 
parate objects is today more conveniently achieved 
with packages, and they are more frequently 
stored in files rather than in saved workspaces. 


Definition of a group: A group is a global ob- 
ject, and hence its name must be distinct from the 
name of any other global object in the workspace. 
A group consists of a list of names. The names 
must be well formed, but need not refer to any- 
thing actually present in the workspace. 


Forming a new group: A group is formed by 
the system command )GROUP, used in the form: 


)GROUP GNAME OBJ1 OBJ2 OBJ3 ... 


in which GNAME represents the name chosen for 
the group, and OBJ1 OB/J2 etc. are names that are 
to be members of the group. 


Expanding the membership of an existing 
group: To add new names to the list of members 
of a group, you use the system command 
)GROUP followed by two occurrences of the name 
of the group, and then the names to be added. For 
example, to add WEW1 and NEW2 to the existing 
membership of a group called GNVAME, you’d write 


)GROUP GNAME GNAME NEW1 NEW2 


Dispersing a group: A group is dispersed by the 
command 


)GROUP GNAME 


in which the group name is used alone, with no 
members following it. This erases the name of the 
group, but has no effect on the objects that were 
named in its membership list. 


Removing names from membership in a group: 
There is no mechanism to remove some names 
from the namelist but not others, other than to 
disperse the group and then form a new group 
with a revised membership list. 


Listing the names of groups defined in the 
workspace: The command 


)GRPS 


causes the system to display the names of groups 
defined in the workspace. 


Displaying the membership of a particular 
group: The command 


)GRP GNAME 


causes the system to display the list of members 
of the group GNAME. 


Watch out: The commands )GRP GNAME and 
)GROUP GNAME appear very similar, but the first 
asks the system to list the membership of GNAME, 
while the second disperses the group GNAME. 


Effect of copying a group: By copying a group 
from a saved workspace, you receive in the active 
workspace the group’s name and membership list, 
together with all those objects whose names appear 
in the membership list and exist as global objects 
in the source workspace. Thus the command 


)COPY WSNAME GNAME 


causes both the membership list of GVAME to be 
copied into the active workspace, and also the 
global objects to which those names refer in the 
saved workspace. For each name that is a member 
of GNAME but does not exist as a global object in 
the saved workspace from which you’re copying, 
the system does nothing. In particular, it does not 
free the existing use of the name in your active 
workspace (whereas [PDEF would). The system 
does not report NOT COPIED or NOT FOUND for 
the non-existent objects (even though it would if 
they were named directly in the argument of 
)COPY). 


Effect of erasing a group: Using the name of 
a group as an argument of the system command 
)ERASE causes the system to erase the group and 
also each of the names on its membership list that 
exists in the active workspace as a global object 
and is free to be erased. An active function is not 
free to be erased. When some of the members of 
a group can’t be erased (because they aren’t there 
or because they aren’t free to be erased), erasing 
the group does not cause the message NOT 
FOUND or NOT ERASED (even though it would if 
the objects were named directly in the argument 
of )ERASE). 


Effect when a member of a group is itself a 
group: Suppose you have a group named 
GNAME and one of its members is the name X. 
Suppose that X is itself a group. Then a command 
to copy or erase GNAME will copy or erase the 
group X (that is, the name X and the list of names 
that are members of X) but not the objects that 
are mentioned in the membership list of X. Thus, 
the copying or erasing applies only to the immedi- 
ate members of GNAME, and does not propagate 


any further. 
$ 
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Reflecting SHARP APL System 
as of 1 May 1979 


Appendix D: 


SCALAR MONADIC FUNCTIONS 
A A TS 


+Y Y 

=F Negative Y 

xY Signum Y 

sy. Reciprocal of Y 

*xY e to the Y-th power 

ly Ceiling of Y 

LEY Floor of Y 

|Y: Absolute value of Y 

eY Natural logarithm of Y 
Vy Factorial Y; Gamma Y+1 
oY Pi times Y 

?Y A random number from 1Y 
~Y Not Y 


REFERENCE CARD 


SCALAR DYADIC FUNCTIONS 


X+Y X plus Y 

X-Y X minus Y 

XxY X times Y 

XY X divided by Y 

XxY X to the Y-th power 

XTY Maximum of X and Y 

XLY Minimum of X and Y 
X-residue of Y 
Base-X logarithm of Y 
Binomial coefficients: 
Number of size-X subsets of Y items 
See trigonometric functions 
X less than Y 
X less than or equal to Y 
X equal to Y 
X greater than or equal to Y 
X greater than Y 
X not equal to Y 
X and Y 
X or Y 
Not both X and Y 
Neither X nor Y 


Subject to axis operator [J] 
Subject to index origin DIO 
Subject to comparison tolerance CT 
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TRIGONOMETRIC FUNCTIONS 
ReXOY 


R R 

(1-Y*2)x.5 

Sine Y Arcsin Y 
Cosine Y Arccos Y 
Tangent Y Arctan Y 
(1+Y*2)*.5 ( 1+Y*2)*.5 
Sinh Y Arsinh Y 
Cosh Y Arcosh Y 
Tanh Y Artanh Y 


NMOFWNR OPS 


Note: When X is 1, 2 or 3, Y is in radians. 
When X is 1, 2 or 3, R is in radians. 


NON-SCALAR FUNCTIONS 


Reshape Y to have shape X 

Shape (i.e. length of each axis) of Y 

Y-th elements of X 

First locations of Y within vector X 

Y consecutive integers from origin (0 or 1) 

Membership; 1 for each element of X found anywhere in Y 
Representation of Y in number system X 

Value of the representation Y in number system X 

X integers selected randomly without repetition from 1Y 

Rotation by X along the last axis of Y 

Rotation by X along the first axis of Y 

Reversal along the last axis of Y 

Reversal along the first axis of Y 

Transpose of Y according to X 

Transpose of Y; (1ppY)&Y 

Catenate or laminate Y to X along last axis 

Ravel of Y (makes Y a vector) 

Take first or last X positions along axes of Y as X is positive or negative 
Drop first or last X positions along axes of Y as X is positive or negative 
X is assigned the value of Y 

Index vector such that Y[AY] is in ascending order 

Index vector such that Y[YY] is in descending order 

X (Boolean) compressing along the last axis of Y 

X (Boolean) compressing along the first axis of Y 

X (Boolean) expanding along the last axis of Y 

X (Boolean) expanding along the first axis of Y 

Matrix divide; solution of linear systems with coefficients Y and results X 
Generalized matrix inverse of Y 

Executes the character vector or scalar Y 

Character representation of Y 

Numeric expression Y is converted to character according to control vector X 
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MONADIC OPERATORS 


f/ f} Reduction: Derives the monadic function “f reduce.” 
A f Scan: Derives the monadic function “f scan.” 
f may be any primitive scalar dyadic function. 
The derived functions “reduction” or “scan” are subject to the axis operator. 


DYADIC OPERATORS 


f(T] Axis: Selects one axis I along which function f acts. f may be any of: 
, > / 4 \ X or any of the derived functions produced by the reduction or scan 
operators. J is DIO dependent. 

f.g Product: Forms dyadic function “g outer product” or “f.g inner product.” 

g may be any primitive scalar dyadic function. 
f may be any primitive scalar dyadic function or null o. 

Example: X+.xY is the ordinary matrix product of X and Y. 

Xo.+Y is the divide outer product of X and Y. 


FUNCTION DEFINITION 


Function definition is opened or closed by V. Use of ¥ at the close locks the function. The following 
are valid with open definition. 


[0] Display entire function 

[m0] Display line m 

[Om] Display from line m to the end 

[m] (Re)define line m 

[Ami m2. . .] Delete lines m1 m2... 

)n Copies last immediate execution line into function definition with line editing 


LINE EDITING 


Where m is line number, and n is cursor position (n>0 and n<OPW), line editing evoked: 


Immediate Execution Function Definition 


One-pass ) or )O [m00] 
Two-pass )n [mOn] 


One-pass: Displays line; positions cursor at right end. 
Two-pass: Displays line; positions cursor below line at position n to accept editing instructions. 


Editing instructions: 

To left of dot or comma: / deletes characters; n inserts n blanks. 

To right of first dot or comma: text is inserted before character above dot or comma. 
Following comma: system displays amended line; awaits new editing instructions. 
Following dot: system acts on amended line. 

Following neither: one-pass editing of amended line in effect. 
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OTHER USES OF SYMBOLS 
ee e e E T 


Parentheses for nesting 

Brackets for indexing 

Quad for input-output 

Quote-quad for character input-output 
Quote to delimit a character constant 
Lamp to indicate a comment 

Negative sign in numeric constants 
Exponential notation 

Delta; trace (TA) and stop (SA) control 
I-beam for system functions 

Decimal point 

Caret to locate an error 

Semicolon to separate list elements 
Diamond to separate statements 

Branch 

Colon to delimit labels and passwords 
Squish-quad to display an (otherwise) non-printable character 


The following characters are also recognized but have no specific use in APL: 


airen” 
¢w}a>u_ 


SYSTEM FUNCTIONS 


FORMATTING WITH (FMT 


'fp,fp, ....fp' OFMT (expr;expr; ... ;expr) 
d Number of digits 
expr Scalar, vector, or matrix 


q Qualifiers (optional) 
fp Format phrase ank if zero 


m Aw Character data C. Comma insertion (not with G) 

m q E w.d Exponential fraction ke Scaling by 10*e 

mq F wd Fixed-point fraction ` L Left justify (not with G) 

mqiw Integer Z Leading zeros (not with G) 

mXn Relative reposition M<text> Left of negative value 

mT7n Absolute reposition N<text> Right of negative value 

<text> Text insertion P<text> Left of non-negative value 

m q G<text> Picture Q<text> Right of non-negative value 
R<text> Background 

Repetition factor (optional) S<text> Symbol substitution 


Amount of positive or negative displacement Text-delimiting characters 
<c (f Left text delimiter 
Field width >> 0M Matching right text delimiter 
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FILE SYSTEM FUNCTIONS 


Function Syntax Permission 
a E EL EE EE SS 


DAPPEND EXPR (JAPPEND TN,PN 8 
[APPENDR R+EXPR (JAPPENDR TN,PN 

OAVAIL RHJAVAIL 10 

(CREATE FNM (CREATE TN 

DODROP DODROP TN,N,PN 

DERASE FNM [ERASE TN ,PN 

OFHOLD OFHOLD SVM 

DHOLD OHOLD TN 

DZIB Re]LIB LIB 

R+QWNAMES 

Re{\NUMS 

ReRDAC TN,PN 4096 
ReQRDCI TN,CN,PN 512 
Re{)READ TV,CN,PN 1 
FNM [RENAME TN ,PN 128 
EXPR [REPLACE TN,CN,PN 16 
P QRESIZE TN ,PN 1024 
R4]SIZE TN,PN 1 
MAT DOSTAC TN,PN 8192 or 256 
FNM ()STIE TN,PN Any permission 
FNM (TIE TN,PN 2 
OUNTIE DUNTIE TN 





Component number 

Data resulting from any expression 
Tie number(s) 

File name 

Library number 

3-column access matrix 

Integer 

Positive integer 

Passnumber or 10 

Result 

Scalar, vector, or 2-row matrix of integers 


* No permission required to use; reports files you own or to which you have any access. 


The syntax for FNM of OCREATE and QRENAME is 
' {library-number] filename [file-size-limit]' where [ .. . ] is optional. 


Complete access to a file can be given by a permission code of 1. 
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N-TASKS AND B-TASKS 


R+]RUN 'signon loadwsid savewsid cpulim conlim' 
Initiates an N-task. The character, colon, must be supplied, but signon and 
loadwsid may each be elided. (cpulim in CPU units; conlim in seconds; 0 
means no limit.) 

R 

Split-ws new task 

Successful n=taskid 

Invalid argument at character n 

System capacity for N-tasks exhausted 

User N-task quota (4) exceeded 

WS quota exhausted 

WS full in loadwsid 

Symbol table full in loadwsid 

Sign-on number not in system 

Sign-on number locked out 

loadwsid not found 

loadwsid invalid LX 

System capacity for tasks exhausted 

User may not use QRUN 

Hardware error 


6 
10 
11 
12 
13 
14 
15 
16 


oooocooocco°o°coco°coc°o 8 Bo 


R+QRUNS Task information in matrix format. Columns are: taskid user initiator 
tasktype cpu con cpulim conlim. (cpu in CPU units. con in seconds.) 


Re{]BOUNCE TASKID Terminates tasks specified by TASKID. Task executing OBOUNCE must be user 
or initiator to be successful. Result is Boolean indicating successful terminations. 


ROUT PR,TN Sets/displays mode in which data is printed. DOUT 10 returns the current setting 
without modification. Otherwise the previous setting is returned and the mode 
set as follows: Print data at terminal if PR is 1. Append data to file tie number 
TN if TN is not zero. If TN is zero do not append data to file. 


B-task requests are submitted via the functions in WS 1 BTASKREQ. 


EVENT TRAPPING FUNCTIONS AND VARIABLES 
Name Syntax Definition 


DER DER Event report. Three-row matrix set by system following certain 
events. 


OSIGNAL [X] OSIGNAL Y Abort function now at top of state indicator, and signal event Y, 
optionally with title X. 


OTRAP OTRAP+Y Trap definitions. You set, system uses. [TRAP contains trap defini- 
tions; when a matrix, one per row; when a vector, delimited by first 
character. System resets an invalid DTRAP to ''. 





Appendix D: REFERENCE CARD 300 


TRAP DEFINITIONS 


Form 


301 


S 
N 
E 
C 


EVENT 


Effect 


STOP. 
NEXT. Look for event in next DTRAP. 

[trap line] EXECUTE. Execute trap line. 

[trap line] Cut back state indicator to function to which [TRAP is local, and 
execute trap line. 

[EXIT | CLEAR] Upon return to immediate execution, do nothing, exit function, or 
clear workspace. 


NUMBERS 


Any error WS NOT FOUND 

WS FULL WS NOT READABLE 
SYNTAX ERROR SWAP ERROR, CLEAR WS 
INDEX ERROR (Not trappable) 


RANK 


ERROR SYSTEM ERROR, CLEAR WS 


LENGTH ERROR (Not trappable) 

VALUE ERROR INTERFACE QUOTA EXHAUSTED 
FORMAT ERROR NO SHARES 

DOMAIN ERROR INTERFACE CAPACITY EXCEEDED 
SYMBOL TABLE FULL SHARE TABLE FULL 

NONCE ERROR PROCESSOR TABLE FULL 


FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 
FILE 


TIE ERROR IDENTIFICATION IN USE 
ACCESS ERROR OPP ERROR 

INDEX ERROR OPW ERROR 

FULL OIO ERROR 

NAME ERROR ORL ERROR 

DAMAGED OCT ERROR 

TIED DAT ERROR 

SYSTEM ERROR Any interrupt 

SYSTEM NOT AVAILABLE STOP 

SYSTEM TIES USED UP ATTENTION 

TIE QUOTA USED UP INTERRUPT 

QUOTA USED UP INPUT INTERRUPT 
RESERVATION ERROR SV INTERRUPT 

SYSTEM NO SPACE FILE INTERRUPT 
COMPONENT DAMAGED FILE BACKUP INTERRUPT 


WS LOCKED Return to immediate execution 
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PACKAGE FUNCTIONS 


A package is a single data object containing a heterogeneous collection of names and the referent (if 
any) of each. 


Function Syntax Definition 


OPACK P«{JPACK NL Creates a package P from namelist* NZ. 
P+NL QPACK Y Creates a package containing the array or package Y with the 
names specified in WL. 


OPDEF P Defines in the WS the names in P and their referents, if any. 
NL DPDEF P As above, except only names included in NZ are defined. 


P1+NL DPEX P2 Package of names and their referents selected from P2 but 
excluding those mentioned in WL. 


R+P1 DPINS P2 Package insertion. R is a package containing all names and 
referents from P2, together with names from P1 that are not 
in P2, and their referents. 


R4JPLOCK P Package lock. R is a package identical to P but in which all 
functions are locked. 
RNL Q)PLOCK P As above, but functions named in NZL are locked. 


OPNAMES R+Q)PNAMES P Matrix of names in package P. If P is not a package, returns 
10. 


OPNC RNL DPNC P Package nameclass, analogous to DNC. 
-R CLASS 
“1 Name in package with no referent 
0 Valid name, not in package 
2 Name refers to variable 
3 Name refers to function 
4 Ill-formed name 
R+PNC P Class of each name in P. Equivalent to 
R+(QPNAMES P) OPNC P. 


R+PPDEF P Protective definition. Defines in the WS those names in P 
which had no referents in the WS. R is matrix of names 
previously defined (and left unchanged). 

R+NL QPPDEF P As above, except only names in NL are considered. 


OPSEL R«NL OPSEL P Package containing names in WL and their referents, selected 
from P. 


OPV AL R-X DPVAL P The value of the variable named in X from package P. 


*Namelist: An argument indicated by WZ is a namelist. It may be a matrix, one name per row, or 
a vector in which names are separated by blanks. Except where “matrix WL” is specified, either form 
may be used. Where the system returns several names in a result, they are always arranged as a 
matrix. 
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OTHER SYSTEM FUNCTIONS AND SYSTEM VARIABLES 


Function Syntax 


DAT RAJAI 


R4JARBIN Y 


QARBOUT Y 


RAV 


RICR Y 


RDL Y 


REX Y 


ReI DFD Y 


Rei DFD Y 
Re2 DFD Y 


Definition 
Returns a vector of accounting information for T-tasks. 


ELEMENT CONTENTS 

User number 

CPU units this session 

Connect time this session 

Keying time this session 

Characters this session 

Cumulative CPU units since last billing 

Cumulative connect time since last billing 

Zero (unused) 

Cumulative characters since last billing 
DAJ is subject to extension. Do not assume a specific length. CPU 
in milli-CPU units. Times in milliseconds. 


Arbitrary input/output. Y is transmission codes sent to terminal; 
effect depends on the terminal. R is numeric representation of user’s 
response. 


Arbitrary output. Y is transmission codes sent to terminal; their 
effect depends on the terminal. 


Atomic vector. Vector of all 256 unique characters in the order of 
their internal representation. 


Character matrix containing canonical representation of the function 
named in Y. 


Delay. Causes at least Y seconds of delay in execution before resum- 
ing. R is actual delay in seconds. 


Expunge. Y is matrix of names whose local use is to be freed. R 
is a Boolean vector indicating which names have been freed. 


Function definition. I specifies the particular function definition 
service. Y is a character vector or array. 

Character vector representation of the function named in Y. 
Character matrix representation of the function named in Y. 
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Function Syntax Definition 
Sse sae SET 


R«3 DFD Y Y is a vector or matrix character representation of a function. If 
3 DFD is successful the function is defined in the WS. R is the 
function name. If unsuccessful, R is a two-element numeric error 
report. Element 2 of R is the location within Y that the error was 
discovered. Element 1 is documented below: 

R[1 ERROR 
WS full 
Defn error 
Char error 
Symbol table full 
Unmatched quotes 
System error; notify your SHARP APL representative 
Empty line 

R<6 OFD NL NL is a namelist* of names whose visible use is to be freed. R is 
a matrix of names which the function did not free. 

R+7 DFD NL NL is a namelist of functions to be locked. R is a matrix of names 
which the function did not lock. 


ReOFI Y Converts each field within a character vector to a number. Each 
field containing something other than the representation of a num- 
ber is reported as 0. Fields are separated by blanks. 


X FMT (A;B;C) Format. See separate section of this card. 


ReFX Y Y is the canonical representation of a function, as a character ma- 
trix. When successful, the function is defined in the WS, and R is 
its name. When unsuccessful, R is the origin-0 index of the row of 
Y at which a fault was discovered. 


RDC Line counter. Vector of line numbers corresponding to )SI. 
DLOAD Y Loads the WS named in Y. 


ReQNC NL Nameclass of each name in the matrix NL. 
R CLASS 
0 Name is free 
1 Label 
2 Variable 
3 Function 
4 Other 


R+OWL Y Namelist. Y is a scalar or vector each of whose elements is 1, 2 or 
3. (See DNC.) R is a matrix of visible names whose class is a 
member of Y. 

R-X OWL Y X is a scalar or vector of alphabetic characters. R is restricted to 
names beginning with letters in X. 


*Namelist: An argument indicated by NL is a namelist. It may be a matrix, one name per row, or 
a vector in which names are separated by blanks. Except where “matrix NL” is specified, either form 
may be used. Where the system returns several names in a result, they are always arranged as a 
matrix. 
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Function Syntax 


OQLOAD OQLOAD Y 


Ors 
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RAITS 


RAJUL 


RAVI Y 


RAWA 


R-I (WS Y 


R+1 (WS Y 


Re2 (WS Y 


R+3 (WS NL 
Rey CWS NL 


Definition 
Loads the WS named in Y without displaying save-date. 


Timestamp. 7-element integer vector containing current year, 
month, day, hour, minute, second, and millisecond, in UTC. 


User load. Number of tasks signed on. 


Boolean vector indicating whether each field within Y is a well- 
formed representation of a number. (See DFI for “field.”) 


Workspace available. The number of bytes remaining in the work- 
space. 


Workspace descriptions. I specifies the particular description re- 
quired. 
Namelist of certain classes of identifiers in the workspace. Y can be 
the sum of any subset of 1 2 4 8. 
RESULT 
Function 
Variable 
Group 
Label 
RESULT 
Character workspace ID 
Character matrix )SI 
Workspace environment 
ELEMENT CONTENTS 
1-6 Unused (value 1) 
7 ) SYMBOLS 
8 Number of symbols in use 
9 User number 
10 Port signed on 
11 Taskid 
12 Translate set 
o None (because N-task or B-task) 
Correspondence 
BCD 
TY33 (64 char ASCII) 
Typewriter pairing ASCII 
Bit pairing ASCII 
2 [WS 3 is subject to extension. Do not assume a specific length. 
4 Vector of three elements 
ELEMENT CONTENTS 
1 Workspace size (bytes in use) 
2 Workspace owner number 
3 ORDCI-style timestamp 
Character matrix of names in group named in NZ. 
Bytes required to store each object named in WL. 


wn elko Fm RIK 
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Function Syntax Definition 


R+5 (WS NL )SIV information, one row per name in NZ, one column per )SI 
level, plus one for global environment. 


R MEANING 


1 Not localized at this level 
Undefined (but localized ) 
Function 
Variable 
Group 
8 Label 
R+6 (WS NL The value of the variable named in WL. 


SHARED VARIABLE FUNCTIONS AND VARIABLES 


Function Syntax Definition 


OSV@ Re{SVQ Y Shared variable query. When Y is empty, R is matrix of processor 
IDs with outstanding offers to you. When Y is a processor ID, R 
is matrix of names in outstanding offers to you from Y. 


Re[X] DSVO Y Shared variable offers. Monadically, R is degree of coupling of 
names in Y. Dyadically, offer to share each name in Y with corre- 
sponding processor in X. R is degree of coupling following offer. 


Re[X] Osvc Y Shared variable control. Monadically, R is access control vector for 

each name in Y. Dyadically, access control for each name in Y is 
set to XVX, where X is access control previously set by partner. R 
is resulting access control. 

Effect of 1 in element: 

You may not set again until partner has used or set 

Partner may not set again until you have used or set 

You may not use again until partner has set 

Partner may not use again until you have set 


RSVS Y Shared variable state of names in Y 
0 000 Not a shared variable 
You and partner are both aware of current value 
You have set, but partner has not used 
Partner has set, but you have not used. 


RSVR Y Shared variable retraction. Retracts offer to share names in Y. R is 
degree of coupling before retraction. 


R+QSvVW Y Set active workspace’s clone ID to Y. R is clone ID in effect after- 
wards. 1 is invalid clone ID. 


ose State change variable, value 0 or 1. While WS has valid clone ID, 
system sets to 1 following each offer, retraction, or change to 
OSVS; when no change has taken place, delays until the next 
change. 





Appendix D: REFERENCE CARD 306 





SYSTEM VARIABLES 


Lcr 


[ro 
OLX 
OPP 


OPW 
DRL 


Comparison tolerance. Maximum relative difference between two numbers considered 
equal by SHARP APL. Value in clear WS is approximately 1Z 14. Meaningful 
range: 0 up to but not including 16* 8 (=2.328F 10). 

Index origin. Value in clear WS is 1. Meaningful value: 0 or 1. 

Latent expression executed upon WS load. Value in clear WS is ''. 

Print precision. Number of digits printed when numbers are displayed. Value in clear 
WS is 10. Meaningful range: integer, 1 to 18. 

Print width. Value in clear WS is 132. Meaningful range: integer, 30 to 250. 
Random link. Value in clear WS is 16807. Meaningful range: integer, 1 to 
~2+2%34 (=2147483646). 


Session Variables 


OAT 
DSP 
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Horizontal tab positions. Value at start of task is 10. 
Session parameter. Value at start of task is ''. 


ARBOUT 
BTASKREQ 
FILEAID 
FILESORT 
FORMAT 
HSPRINT 
NETWORK 
NEWS 
PUBLICLIBS 
REFERENCE 


WSTRANSFER 


SELECTED PUBLIC WORKSPACES 


Tables of ASCII, BCD, and Correspondence transmission codes 
B-task submission 

Functions complementary to file functions 

File sorting utility 

Functions complementary to DFMT 

Remote highspeed print 

Documents communication network 

System enhancements, schedules, phone numbers 
Applications libraries 

On-line reference card 

SHARP APL Technical Notes on-line 
Timestamp encoding and decoding 

Accounting information by month 

Workspace control functions 

Documentation of )TERM 

Source-format WS interchange 
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SYSTEM COMMANDS 


Note: Bracketed words are optional. | separatés mutually exclusive alternatives. 


) [n] Allow editing of immediate execution line at position 
n 

)nnnnnnn [:password] Sign-on; invalid sign-on acts as )BLOT 

) BLOT Print a mask for typing secure information 

)CLEAR Clear the active workspace 

)CONTINUE [HOLD] [:password] Terminate a session and store the active workspace in 
CONTINUE; set password 

) [P] COPY name [:password] [list] Copy global objects from a workspace; )PCOPY protects 

_ contents of active WS from being overwritten 

)DROP name [:password] Delete a stored workspace 

)ERASE list Erase global names 

)FNS [letters] List names of functions starting with letters 

)GROUP name [nmi nm2 nm3 ...] Forms group name with members nmi nm2 nm3 ...; 
with no members, disperses name 

)GRP name List members of group 

)GRPS [letters] List names of groups starting with letters 

)KEYB [LOCK|NOMSG] Unlock or lock keyboard, or reject messages 

)ZIB [nnn] List names of workspaces in library 

)LOAD name [:password] Activate a copy of a stored workspace 

)MSG [N] taskid text Send message to terminal of designated task; )MSGN 
does not lock sender’s keyboard to receive reply 

)OFF [HOLD] [:password] Terminate a work session; set password 

)OPR[N] text Send message to SHARP APL operator; )OPRW does 
not lock sender’s keyboard to receive reply 

)PORTS aaa|nnnnnnn List port numbers and taskids of tasks matching code 
aaa or account nnnnnnn 

) RESET Clear the )SI stack 

)SAVE [name] [:password] Store a copy of the active workspace 

)SEAL Lock all functions in the active workspace; prevent dis- 
persal of contents 

)SI[V] Display the state indicator; )SIV displays state indica- 
tor and localized names 

)SYMBOLS [n] Display/set symbol table size 

)TERM [name] Display/set terminal type (See WS 5 TERM for current 
list of names.) 

)VARS [letters] List names of variables starting with letters 

)WSID [name] [:password] Display/set workspace name 


Valid names for )TERM: 


AJ832 ASCII DCTTAPE DCTTTYS GET1200 HP2641 
IBM2741 MRX1240 REALTTY SDATA TEK4013 TY33 
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SHARP APL TECHNICAL NOTES 


SATN-O 
SATN-1 
SATN-2 
SATN-3 
SATN-4 
SATN-5 
SATN-6 
SATN-7 
SATN-8 
SATN-9 
SATN-10 
SATN-11 
SATN-12 
SATN-13 
SATN-14 
SATN-16 
SATN-17 
SATN-18 
SATN-19 
SATN-20 
SATN-21 
SATN-22 
SATN-23 
SATN-24 
SATN-25 
SATN-26 
SATN-28 
SATN-29 
SATN-30 
SATN-31 
SATN-32 
SATN-33 





1 JAN 76 
1 JAN 76 
14 FEB 79 
1 JAN 76 
1 APR 78 
1 AUG 78 
1 JAN 76 
1 JAN 76 
1 MAR 79 
1 AUG 78 
1 JUN 78 
1 JAN 76 
1 JAN 76 
MAR 78 
AUG 78 
APR 76 
30 JUN 76 
1 JUL 76 
1 JAN 77 
1 JUN 78 
1 JUN 78 
1 JAN 79 
JUL 78 
MAR 77 
MAY 77 
10 SEP 77 
11 JUL 77 
15 JUN 78 
JAN 79 
FEB 79 
MAR 79 
MAR 79 





SATN Introduction 
TASKID 

Control Messages 
flour 

N-tasks AND B-tasks 
Batch APL 

Execute 

Latent Expression 


2 HSPRINT 


Usage Inquiry System 


2 SORTREQ 


) RESET 

)COPY 

Early Warnings 

Package—A New Variable Type 
File System Must-Write Buffers 
Formatting Primitive 

DEMT 

FILEPRINT 

System Variables, Session Variables, and System Functions 
(Ws AND DFD 

APL Workspace Transfer 
Comparison Tolerance 
)SYMBOLS 

Extensions to Argument Passing 
Enhancements to the File System 
Terminal Control 

System Time and Timestamps 
Numeric Display 

Line Editing in SHARP APL 
Shared Variables 

Event Trapping 
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An item shown in boldface indicates a term that 
appears in the title of a chapter or section. In some 
instances, an entire heading is reproduced as an 
item in the index. 


Where an entry refers to an APL symbol, the name 
of the symbol is spelled out. For example, “iota” 
appears as the first word of an entry, rather than 
the 1 symbol. However, there are entries that start 
with the symbols 0 or M. They are alphabetized as 
if they were spelled “quad” or “quadprime,” re- 
spectively. 


A 


A: OFMT character format, 202 
A Programming Language (book), iv 
abort execution: naked branch, 179 
OSIGWAL, 107 233 
)RESET command, 272 
trap action C, 113 114 118 232 
absolute value: see magnitude, 125 
Access control (file), 102 
Access control (shared variable), 92 
descriptions of monadic and dyadic DSVC, 255 
access control (shared variable): assure effective 
communication, 85 
meanings of some possible settings, 95 
point of view, 90 
access matrix (file): Format, 102 
How system selects permission code, 103 
Rules governing, 103 
access matrix (file), 102 103 104 217 
immediate effect of update, 104 
inadvertent exclusion of owner, 104 
Account information: description of QAT, 222 
account initials: )PORT command, 271 
Account number: associated with task, 7 
account number: argument and result of SVQ, 252 
associated with file, 9 102 212 214 215 217 219 
associated with saved workspace, 8 226 227 266 
269 272 276 
field in argument of (LOAD or OQLOAD, 242 
field in left argument of file-create function, 215 
field in left argument of file-tie functions, 212 
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in file access matrix, zero means “any,” 102 

initiator of task, 198 

owner of task, 198 227 

persons permitted access to file, 102 217 

user directory, 2 

user who wrote file component, 214 219 
accumulated usage: see “cumulative” 
ACM (Association for Computing Machinery), iv 


v 
action code: field within trap definition, 111 113 
232 
activation of saved workspace: see )LOAD, DLOAD, 
O@LOAD 
active function: restriction on use of )ERASE, 268 
active tasks: (RUNS reports, 198 
active workspace: distinguished from saved work- 
space, 8 
effect of )SAVE command, 273 
processor or partner in sharing variables, 84 
sharing between two, 91 
system functions that report environment, 40 
where all calculation takes place, 6 37 
adding new line to a function definition, 36 64 
Addition, 128 
addition: identity element, 187 
precision and order of execution in reductions and 
scans, 182 
adjacent fields: separation with dyadic ¥, 176 
Advantages and disadvantages of the del func- 
tion editor, 36 
algebra: conventional order of evaluation, 23 24 
Algebraic negation, 125 
alignment: exponential display, 177 
system-default displays of rank 2 or higher, 52 
“all”: use of A/Y, 185 
all positions along an axis: elision of index, 156 
alpha: symbol for argument in direct definition, 33 
alphabetic characters: list, 57 
selecting names with certain initials, 224 
alphabetization: expression, 159 
names reported by command )FWS or )VARS, 268 
result of 1 [WS but not ONL, 226 
ALREADY SIGNED ON: error during line editing, 71 
following attempted sign-on, 264 
still possible to send message to system operator, 
269 
Alternate forms for appearance of defined func- 
tion, 33 
Alternate forms for the arguments and result of 
a defined function, 34 
alternating sum: Maclaurin series, 193 
alternating sum and product: reduction by non-asso- 
ciative function, 187 
altitude of unit circle, 137 
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ambiguity when an argument is both used and as- 
signed a new value, 24 169 

Ambiguous use of SVQ or dyadic DSVO, 90 

And: logical function, 134 

and: identity element, 187 

“any”: use of v/Y, 185 

any error: event number 0, 110 

any interrupt: event number 1000, 110 

APL character set, 2 54 

APL DEFINITELY HUNG, 279 

APL interpreter: file system independent, 105 

APL language: system functions considered as ex- 
tensions to, 28 

APL Language (IBM manual), v 93 

APL WOT AVAILABLE, 279 

APL PLUS, iv 

APL PROBABLY DOWN, 279 

APL PROBABLY HUNG, 279 

APL Quote Quad (publication), v 

apostrophe: see “quote” 

appearance of defined function: alternate forms, 33 

append: file, 79 213 214 241 

Append output to file: description of DOUT, 241 

appending new line to function definition, 36 64 

appending new row or column to matrix, 150 

Appending normal output to file, 79 

application development: rapid, 2 

Application of [CT to monadic functions, 122 

application that uses event trapping: design, 117 

Applications of OUT, 79 

applications of shared variables, 84 

Applying a primitive function to all elements of 
an array, 46 

Applying a scalar dyadic function to array argu- 
ments, 46 

approximation: fitting polynomials to observed data, 

8 


ARBIN: control message mnemonic for arbitrary 
input/output, 82 
Arbitrary input mode, 73 
arbitrary input mode, 62 
Arbitrary input/output: description of JARBIN and 
DARBOUT, 239 
arbitrary input/output, 12 52 55 62 73 78 79 81 
82 129 234 239 240 262 
control message in DOUT file, 81 
arbitrary output: cursor keeps no account, 262 
ignores DPW, 262 
ARBOUT: control message mnemonic for arbitrary 
output, 82 
ARBOUT workspace: public workspace containing ta- 
bles for arbitrary I/O, 78 
arc: radian measure, 137 
arccos: selected by left argument of 0, 136 


archiving of files, 10 100 
arcosh (area of hyperbolic cosine): selected by left 
argument of 0, 136 
arcsin: selected by left argument of 0, 136 
arctan: selected by left argument of 0, 136 
argument: compared with shared variable as means 
of receiving input, 30 
explicit, needed to construct phrases from defined 
functions, 32 
instance of function’s domain, 12 
may be an expression, 18 
operator, 13 
value in evaluating a function, 13 
argument passing, 35 43 
Argument placement, 21 
arguments: number, 19 25 35 
requirements that they conform in rank and 
shape, 25 46 
arguments and result of a defined function: alternate 
forms, 34 
arguments of a dyadic function: order of evaluation, 


arguments of a function: how written, 18 23 
arithmetic functions: inapplicable to package, 245 
Arithmetic product and quotient, 129 
Arithmetic sum and difference, 128 
array: argument of axis operator, 22 
as data object, 11 
axes, 13 14 16 22 27 45 47 48 49 53 63 134 138 
140 142 143 144 145 149 153 155 156 
157 161 182 185 186 187 188 191 206 
260 
empty, 47 
function applied to all elements, 2 45 
multi-axis, blank line used to separate successive 
axes, 53 
number of lines required to display, 53 
rank, 45 
shape, 46 
constant, 13 
array data: Two types, 47 
Array data structure, 44 
array orientation: APL language, 1 
arrays: functions that form, 47 
Arrays and packages, 44 
arrays of arrays: see “nested arrays” 
arrow: left, to indicate assignment, 13 18 20 24 34 
35 38 168 169 170 172 210 
right, in trace of branch taken, 209 
right, symbol for branch, 18 21 23 27 41 42 72 
73 108 114 171 179 180 209 223 239 272 
arsinh (area of hyperbolic sine): selected by left 
argument of 0, 136 
artanh (area of hyperbolic tangent): selected by left 


argument of 0, 136 
ascending order: see upgrade, 158 
ASCII: keyboard, 5 
ASCII: argument or result of )TERM command, 274 
ASCII encoding, 76 
bit-pairing, 74 
reported in 2 [WS 3, 227 
table, 75 
typewriter-pairing, 74 
TY33 64-character, 74 
ASCII terminal, 264 274 
keyboard locking, 268 
Assigning significance to particular axes, 49 
Assignment, 168 
Assignment: indexed, 169 
assignment, 13 18 20 24 34 35 38 168 169 170 172 
210 
expression may include, 18 
multiple, 169 
result of, 169 
when root function is, 20 172 
assignment arrow: used in function header to indi- 
cate explicit result, 35 
assignment of value to a name, 168 
association of name and value: function + denotes, 
13 
associative and non-associative functions: scans com- 
pared, 182 
associative function: reduction by, 187 
asterisk: level to which naked branch cuts back state 
indicator, 73 180 
used to mark field too narrow to display value, 
178 
used to mark suspended functions on the state 
indicator, 41 226 274 
atomic vector: description of DAV, 54 
attention, 55 64 95 110 111 119 220 240 257 260 
268 270 279 
distinguished from interrupt, 55 
effect on file hold, 220 
event description, 279 
ignored because of DTRAP, 119 
to break delay imposed by ODZ, 260 
trappable event, 111 
ATTN: ignored because of [TRAP, 119 
representation in arbitrary input, 240 
terminal key, 55 
to abandon terminal-to-terminal message, 270 
to break delay imposed by ODL, 260 
to break file hold, 220 
to correct current entry line, 64 
to interrupt shared variable delay, 95 257 
to request use of locked keyboard, 268 
to signal interrupt, 110 
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ew 


authorization, file: see permission 
auto-load: following session terminated by 
OBOUNCE, line-drop, or )CONTINUE, 198 
270 271 
automatic display of result, 5 19 20 52 53 171 173 
178 262 
suppressed when root function is assignment, 20 
when root function is 2, 19 
Automatic trapping of errors and interrupts, 106 
autonomous processors: modelled with shared varia- 
bles, 85 
auto-start: [ZX to provide, 42 119 197 243 258 259 
266 269 
auxiliary processor, 91 
processor ID, 87 
auxiliary storage, 3 
location of saved workspace, 8 
availability: file system, 105 211 
AWAITING FUNCTION FOUR, 279 
aware of shared variable’s current value: which 
partner, 91 255 
axes: Assigning significance, 49 
axes: array having none, 45 
data array, 13 14 16 22 27 45 47 48 49 53 63 
134 138 140 142 143 144 145 149 153 
155 156 157 161 182 185 186 187 188 
191 206 260 
maximum number, 45 
order, 47 
order permuted by transpose, 47 
order reversed by monadic transpose, 144 
package does not have, 48 
permuted or mapped together with dyadic trans- 
pose, 145 
axis: choice for inner product applications, 191 
effect on reduction when has length one or zero, 
185 
hyperbola, 138 
length of each reported by monadic rho, 140 
may have length zero, 47 
new, formed by lamination, 48 
axis along which an explicit representation is ar- 
ranged, 161 
along which catenation or lamination takes 
place, 149 
along which compression takes place, 157 
along which expansion takes place, 157 
along which reduction takes place, 185 
axis along which scan takes place, 182 
axis number: fractional, in lamination, 149 188 
possible value, 188 
Axis operator, 188 
axis operator, 13 16 22 27 142 143 149 157 188 
260 


axis 


axis 
axis 
axis 
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example, 13 

index origin, 260 

with catenate and laminate, 149 
with expand and compress, 157 
with reduce, 188 

with reverse, 142 

with rotate, 143 

with scan, 185 


B 


B qualifier: to represent zero value by blank, 203 
background: text in DFM? display, 203 
Background regarding transmissions to and from 
a terminal, 74 
BACKSPACE: terminal key, 55 
to overstrike prompt with reply, 238 
backspace: character than can be displayed but not 
entered, 56 60 
may not overstrike at some CRT terminals, 56 
to construct characters, 54 
back-up copies of file components: timestamp facili- 
tates, 10 100 
bare output: see [] output or arbitrary output 
base: number system, 160 
Base value, 160 
Base X logarithm of Y, 129 
batch APL, 3 
scheduling, 2 
batch file printing, 3 
batch file sorting, 3 
batch task, 5 8 
active workspace, 6 
adapting from interactive task, 6 
language used, 6 
batch tasks: System functions for, 196 
BCD code, 240 264 
bell: ASCII terminal, 75 268 
Beta function, 132 
billing: account information since last, 222 
billing information: sign-off acknowledgement, 270 
billing rate: different for different types of task, 8 
binary: encoding and decoding number representa- 
tions, 161 
Binomial coefficients, 131 
binomial coefficients: generalized form, alternative al- 
gorithms, 132 
identity element, 187 
bit storage: Boolean internal type, 288 
bit-pairing ASCII, 74 240 
reported by 2 [WS 3, 227 


- bits transmitted to and from terminal: explicit con- 


trol, 239 


blank: argument of [JLOAD or QQLOAD, 243 
column separates fields of system-default display, 
53 
counted as character during transmission, 223 
fill element for take and expand, 47 158 
insertion with [FMT codes X or T, 202 
to represent zero, 203 
to separate action code in trap definition, 113 
to separate elements of numeric constant, 16 51 
to separate fields within argument of DFI or 
DVI, 200 
to separate name and its surrogate, 255 
to separate name of function from name occur- 
ring in its argument, 21 
to separate names within a namelist, 245 
to separate successive axes in display of multi- 
axis array, 53 
to separate successive columns in displays 
produced by dyadic 7, 176 
unwanted, inserted inadvertently during two-pass 
line editing, 67 71 
where needed in an expression, 16 
blank row: argument of OFX or DFD, 207 
blanks: transmission facilitated by tab stops, 251 
block (of a rank-4 array), 45 
block-insertion: during two-pass line editing, 67 265 
)BLOT system command, 265 
setting new password, 271 
body: defined function, 17 34 
body, comment, label: Divisions of a line, 17 
body of a line: Statements within, 17 
Boolean: argument of logical scans, 185 
internal data type, 288 
left argument of compression, 157 
optimization of execution when used to compress 
indexes generated with monadic iota, 154 
result of a logical function, 134 
Boolean array: permutation and partition matrices, 
193 
Boolean function: see “logical function,” 134 
Bounce, 198 
bounce: impossible to trap, 117 232 
may be reported in DER, 232 
bracket: distinction between British and North 
American usage, 15 
brackets: enclose an index, 16 
index, on left of assignment arrow, 169 
to enclose optional fields in descriptions of system 
commands, 264 
to indicate axis operator, 16 
type of delimiter, 15 
Branch, 27 179 
branch, 18 21 23 27 41 42 72 73 108 114 171 179 
180 209 223 239 272 


common forms, 180 
controls number of line to be executed next, 18 
empty, in response to request for {] input, 239 
entered from keyboard, to abandon or resume ex- 
ecution of suspended function, 41 108 209 
marked in trace of function execution, 209 
multi-way, 180 
naked, 18 72 73 179 180 209 239 272 
response to request for [] input, 72 239 
right arrow symbolizes, 18 21 23 27 41 42 72 
73 108 114 171 179 180 209 223 239 272 
within argument of ¢, 171 
within trap definition, to abandon or resume exe- 
cution of function that would otherwise be 
suspended, 108 114 
within trap definition compared with branch 
within argument of 2, 114 
branch arrow standing alone: see “naked branch” 
branch statement, 18 
effect depends upon value of expression to the 
right of it, 21 
effect on line counter, 23 
effect when there are other statements in the 
same line, 21 
branch to empty vector: meaning, 42 
branch to DLC: caution, 223 
branch with action C: caution regarding destination, 
114 
BREAK: representation in arbitrary input, 240 
terminal key, 55 
to abandon terminal-to-terminal message, 270 
o break delay imposed by (DL, 260 
o break delay in use of OSC, 257 
to break file hold, 220 
to request use of locked keyboard, 268 
to signal interrupt, 110 
o signal interrupt but ignored because of 
OTRAP, 119 
Breed, Lawrence M., iv 
British usage: difference from North American re- 
garding terms “bracket” and “parenthe- 
sis,” 15 
BS: variable in workspace 1 WSFNS, 56 
B-task: activity not reported by DAI, 222 
clone ID, 87 
included in DUZ, 224 
OLX to start, 258 
QOTRAP in workspace saved at end, 119 
scheduler, 8 
see also separate publication “Batch Tasks in 
SHARP APL” 
shared variable partner, 91 
terminated by system error, 111 
to submit request, 196 
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unable to handle untrapped errors or interrupts, 
107 
value of session variable at start, 250 
workspace otherwise saved at end avoidable with 
OTRAP action D, 116 
BTASKREQ: to submit B-task request, 198 
buffering of [| output, 236 
effect of using DARBOUT or QARBIN, 240 
Building and testing functions that use event 
trapping, 117 
building blocks: defined functions, 2 
bytes: file component, 214 216 
object in workspace, 228 
total used by file, 214 215 216 281 
bytes per element: internal data types, 289 


C 


C action: cut back state indicator, 113 232 
testing effect of trap line, 118 
C qualifier: to insert commas between triplets of 
digits, 203 
calculation: all takes place in active workspace, 6 
call-by-value in argument-passing, 35 
canonical representation of a function definition, 
205 
capturing terminal output: DOUT, 79 241 
caret: point at which event was detected, indicated 
in DER, 108 109 231 278 
portion of line executed when error encountered, 
278 
CARRIAGE: control message mnemonic for vertical 
forms control, 82 
carriage return: character, 17 
character constant within function’s definition, 
206 
character that can be displayed but not entered, 
56 60 
character vs. terminal control, 75 240 
difference between ASCII and IBM conventions 
regarding how produced, 56 76 
not automatically transmitted at completion of M 
display, 235 
used to signal that line is complete, 17 240 
Cartesian product: arguments of derived outer 
product function, 189 
as result of indexing, 157 
Catenation, 148 
catenation: arguments, 149 
arrays that differ in rank, 150 
axis operator, 149 
distribution over, as property of monadic scalar 
function, 26 
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function that forms an array, 48 
subject to axis operator, 188 
Ceiling, 127 
ceiling: defined in terms of floor, 127 
effect of OCT, 122 127 
central computer: use by many time-sharing users, 
7 


Central computing facility, 7 

change of shared variable state: delay until, 255 
events constituting, 257 

CHAR ERROR, 55 
example of untrappable event, 107 117 
excessive length during line editing, 71 262 
when tab positions undefined, 251 

character: internal data type, 288 


character data, 44 
any entry during [ input is treated as, 73 
argument of ¥, 173 
arithmetic inequality not defined, 135 
cannot occur in same array as numeric data, 47 
converting to numeric with DFI, 200 
formatted with OFMT, 202 
grading and sorting, 159 
character display: reference vector to help use 
DARBOUT or (ARBIN, 240 
character editing: see “line editing” 
character error: [FD condition, 207 


Character input: description of A, 237 
character input mode, 61 73 
leaving, 73 
character output: effect of OPW contrasted with 
numeric output, 262 
Character representation: description of dyadic 
thorn, 173 
description of monadic thorn, 172 
character set: APL, 2 54 
terminal equipment, 4 
characteristic vector, 159 


Characteristics of APL, 1 
characters: display by arbitrary output, reference 
vector, 78 
encoding of numeric argument of [ARBIN and 
OARBOUT, 239 
in APL character set although unused, 57 
in APL language, distinguished from keyboard 
and from system’s internal representations, 
54 
internal representation, 59 
permissible, in argument of 2, 171 
permissible, within representation of a number, 
52 
reference vector of all possible, from DAV, 54 
unrecognized, entry or display, 54 


Characters in the APL language, in the APL sys- 
tem, and at the terminal, 53 
Characters that can be displayed but not entered, 


56 

Characters with special significance at the termi- 
nal, 55 

choice of decimal or exponential form: how system 
makes, 53 


circle-C: transmission control character at IBM ter- 
minals, 78 241 
circle-D: transmission control character at IBM ter- 
minals, 78 
Circular function, 135 
circular function: absence of identity element, 187 
function selected by value of left argument, 136 
outer products, 190 
circular functions as scalar dyadic functions, 136 
class of use of name, 37 38 42 223 224 225 226 228 
229 245 246 247 287 
within package, 247 
classification of distinguished names, 30 
Classification of functions, 25 
classification of members of © family, 136 
Classifying events to simplify trapping them, 109 
CLEAR: action D keyword, 197 
back-up security measure, 116 
convenience at normal end of batch task, 116 
)CLEAR system command, 265 
during [D input, 239 
effect on shared variable, 87 
clear workspace: attempt to save without naming, 
272 
event reported in [ER but not trappable, 111 
possible action in response to event 2001, 110 
size of symbol table, 274 
terminal returns to immediate execution mode, 62 
value of QIO, 260 
value of DZX, 259 
value of DPP, 261 
value of ORL, 260 
CLEAR WS: following )CLEAR, CLEAROUT, or system 
error, 279 
CLEAROUT: function in workspace 1 WSFNS, 116 
197 
makes [TRAP inoperative, 116 
Clone ID, 88 
description of QSVW, 254 
clone ID: default, for new active workspace, 87 
effect on value and delay of OSC, 255 
frozen, 88 254 
required before use of [SVQ or dyadic OSVO, 90 
252 
close quote not distinguished from open quote, 15 
codes: transmission between terminal and system, 74 


collating sequence: not defined on characters, 135 
colon: in argument of DRUN, 196 
in direct definition, 33 
to separate account number from sign-on pass- 
word, 264 282 
to separate line from label, 15 16 
to separate sign-off from password, 270 
to separate workspace name from password, 242 
266 269 272 276 
column: appending a new one to a matrix, 150 
selecting an entire one from a matrix, 155 
column of an array, 45 
column values: see position value, 162 
columnar data: repositioning cursor before display, 
235 
combinations: see binomial coefficients, 131 187 
comma: signals display and another iteration during 
two-pass editing, 67 68 
substitute in OFMT display, 203 
symbol for catenate or laminate, 48 
to separate phrases within left argument of 
DFMT, 201 
to separate triplets of digits in the representation 
of a number, 52 203 
command, system: see system command 
comment: illuminates purpose of a line but is not 
executed, 17 
separated from body of line by lamp symbol, 16 
comment, body, label: Divisions of a line, 17 
comments on this manual, iii 
Common errors during line editing, 71 
common logarithm: see “Base X logarithm,” 129 
communication: effective, requires interlocking of 
shared variables, 85 92 
shared variables as mechanism, 85 
communication link: hold for new sign-on, 270 
communications network, 3 
source of certain messages, 277 
Comparison tolerance, 121 
description of OCT, 259 
comparison tolerance: effect on dyadic iota, 154 
“equal” and “not equal,” 135 
floor and ceiling, 122 126 127 
global value in clear workspace, 42 266 
not involved in automatic type conversion, 290 
residue, 131 
set membership and, 159 
comparisons between SHARP APL and other im- 
plementations, vii 
compiler for defined functions: direct definition, 36 
complement: representing value having sign opposite 
to radix, 164 
complete Beta function: related to generalized bino- 
mial coefficients, 132 
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completeness of a representation, 164 
complex conjugate: implemented as identity on real 
numeric arguments, 124 
component: file, contains an APL object, 3 99 
file, identified by its sequential position, 99 
component count: field of control message, 81 
component information: file, 214 
component number: file, first and next as elements 
of DSIZE, 216 
components: file, dropping first or last, 217 
composite character: see “overstrike to form certain 
characters,” 54 
compound expression: defined, 18 
Compression, 157 
compression: function that forms an array, 48 
perhaps an operator?, 14 
subject to axis operator, 188 
computer: central, used for all computation, 7 
irrelevant to APL language, 10 
Concept of “scalar function,” 26 
concurrent use of same file by several users, 9 10 
85 99 101 212 219 220 
condition of a matrix: criterion of invertibility, 166 
conditional branch, 180 
conditional execution: branch to achieve, 180 
Conformability of arguments and shape of result 
of dyadic scalar functions, 128 
conformability of arguments of a dyadic function, 25 


Conjugate, 124 
connect time: reported by QAZ, 222 
reported by QRUNS, 198 
sign-off acknowledgement, 270 
connectivity: use of v.A, 193 
Consequences of the way the system treats shad- 
owed values of TRAP, 113 
constant: array, 13 51 
certain values or structures must be generated, 13 
how to represent rank greater than 1, 51 
type of data, 13 
vector, how entered from the keyboard, 51 
context: determines valence of a function, 25 
continuation line: dependent on DPW, 262 
indented by six spaces, 236 262 
)CONTINUE system command, 270 
workspace full following attempt to use, 98 
CONTINUE workspace: automatic loading at sign-on, 
271 
automatically saved following bounce of a T-task, 
198 
mode other than immediate execution, 62 
password, 271 
saved following )CONTINUE command, QBOUNCE, 
or line-drop, 270 
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CONTROL: terminal control key, 54 

control: shared variable access, 255 

Control characters ignored, 56 

Control information in each file component, 100 


219 
Control messages, 81 
control messages: from [OUT acceptable to 
HSPRINT, 81 
generated during DOUT to file, 80 
list, 82 


Control of access to a file, 102 

Control of the workspace environment, 42 

control pair: number required in left argument of 
¥, 173 

single pair applied to format several columns, 175 

convenience: avoid interruption or error with 
OTRAP, 119 

conventional algebra: contrast with APL order of 
evaluation, 23 24 

conversion of characters to numbers: see indexing, 
execute, and [FI 

conversion of internal type, 290 

conversion of DRDCI timestamp, 219 

conversion of numbers to characters: see indexing, 
formatting, thorn, DFMT 


Converting and representing data, 200 
coordinated universal time: result of DTS, 224 
sign-off acknowledgement, 270 
sign-on acknowledgement, 264 
coordinates of an array: see axes 
)COPY system command, 266 
applied to group, 37 
during {J input, 239 
effect on function in which stop or trace is set, 
210 
effect on shared variable, 87 
restriction on effect in sealed workspace, 274 
to recover saved QSP, 251 
when object copied is a group, 294 
correcting line before pressing RETURN, 64 
correcting line of a function definition, 63 64 


corrections to this manual, iii 

correspondence code, 240 264 

cos: selected by left argument of 0, 136 

cosecant, 137 

cosh (hyperbolic cosine): selected by left argument 
of 0, 136 

cosine, 137 

cotangent, 137 

coupling: Shared variable: description of [SVO, 
254 

coupling: degree in result of SVR, 97 

duration, 87 101 


duration of file tie and shared variable compared, 
87 101 
CPU limit: field of argument of ORUN, 197 
CPU units: delay until state change, 96 
delay with ODDZ, 259 
reported by QAT, 222 
reported by RUNS, 198 
shared variable inhibition, 95 
- sign-off acknowledgement, 270 
CR: variable in workspace 1 WSFNS, 56 
Create a file, 215 
creating and modifying defined functions: mecha- 
nisms, 35 
CRT terminal: no idles required, 276 
cumulative CPU, connect, and characters transmit- 
ted: sign-off acknowledgement, 270 
cumulative CPU, connect and keying units: JAZ re- 
ports, 222 
cumulative sum, product, maximum, minimum, 185 
cursor: at completion of [f display, 235 237 
at end of line just displayed, in one-pass line 
editing, 66 265 
at start of [ input, 238 
effect of standard output compared with effect of 
arbitrary output, 240 262 
indented before user entries, 5 
positioning, at start of two-pass line editing, 66 
265 
positioning before display of array having rank 
2 or more, 235 
treated as if at left margin following DARBOUT 
display, 238 
cursor reposition: time required, 274 
curve-fitting: polynomial, 168 
cutting back state indicator: action C, 113 114 118 
232 
cyclic functions: sine and cosine, 138 
cyclical repetition: result of reshape, 141 


D 


D action: to force function exit or clear workspace, 
115 197 232 
damage: file, 280 
data: Entering, 51 
data: Structure of, 44 
data: System functions for representing and con- 
verting, 200 
data: inadvertent destruction safeguarded by file ar- 
chiving, 10 
must be of same type throughout, 47 
self-describing, 1 21 47 288 
spatial structure, 45 


summary of forms in which may appear, 14 
syntactic class within a statement, 11 
when named, is called a variable, 13 
when used, must be present in active workspace, 
8 
Data and functions, 11 
data base: public, by means of shared files, 10 
shared variables coordinate access, 85 
Data—constants, results, and variables, 12 
data input mode, 61 
caution against using while files are held, 220 
data storage in a file component: Form, 100 
data storage in workspace, 6 37 224 228 288 
data transmission: aided by minicomputers, 7 
data type: Internal, 288 
date: sign-on and sign-off, 264 270 
when file component was written, 219 
when workspace was saved, 227 
day: element of OTS, 224 
Deal, 178 
deal: value of QRL before execution, 260 
debugging: del editor permits global function to be 
modified during, 36 
stop and trace control, 208 
temporary use of trap definition containing action 
decimal and exponential fields in same display: 
dyadic 7, 178 
decimal format: with dyadic 7, 173 
with FMT, 202 
decimal or exponential form: how system selects, 53 
selection with dyadic ¥, 175 
decimal places: number in display produced by 7, 
174 
decimal point, 15 52 174 177 202 203 
alignment in exponential display of rank 2 or 
higher, 177 
alignment in system-default display of rank 2 or 
higher, 52 
substitute in DFMT display, 203 
decimal system: in representing numbers, 52 160 
declarations (of type, shape, etc.) not used, 1 47 288 
Decode, 160 
decode: evaluation of polynomials, 49 165 
decorators and qualifiers: OFMT, 202 
default, system: data display, 2 5 52 
data display evoked by Q<, 235 
default values of system variables in clear work- 
space, 42 
Define from package: description of DPDEF, 247 
defined function: aborted by [SIGWAL, 117 
aborted by naked branch, 179 
aborted by trap action C, 113 114 118 232 
alternate forms for arguments and result, 34 
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dei editor, 36 38 63 204 278 
how values of the arguments are received, 35 
obtained by QPDEF, 36 
summary of forms in which it may appear, 14 
syntax controlled by function header, 21 34 
when used, must be present in active workspace, 
8 
defined function and its arguments: how written, 18 
defined function within trap line: trappable error, 
114 
Defined functions, programs, and primitive func- 
tions, 12 
definition error: [FD condition, 207 
trappable if arising in argument of OFX or QFD, 


280 
definition mode: short for “function definition 
mode,” 63 


DEFN ERROR: not a trappable event, 117 
trouble report, 279 
degree: best-fitting polynomial, 168 
degree of coupling: shared variable’s, 86 97 254 
del: part of function representation with DFD, 205 
to invoke function editing, 36 63 
del function editor, 204 
advantages and disadvantages, 36 
restricted to global use of function names, 38 
trouble report arising from, 278 
del-tilde: at close of function definition, locks the 
function, 63 
to represent statement within locked function in 
OER, 108 109 233 
Delay: description of DDL, 259 
delay: attempt to carry out inhibited reference to a 
shared variable, 95 
indefinite, until shared variable state change, 96 
delay in display at terminal: caution regarding DDL, 
260 
delayed batch, 5 
delete: characters during two-pass line editing, 66 
265 
file: see erase, 216 
lines of function definition, 64 
workspace: see )DROP, 267 
deletions and insertion: simultaneous, during two- 
pass line editing, 68 265 
delimiter: class of punctuation, 15 
to separate trap definitions with vector (TRAP, 
111 
to set off text within OFMT format phrase, 202 
dependence, linear: prevents matrix inversion, 166 
derived function: produced by operator, 13 22 23 27 
produced by scan operator, 182 
summary of forms in which it may appear, 14 
derived inner product function: domain, 191 
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derived outer product function: domain, 189 
derived scans and reductions: axis operator applies 
to, 188 
descending order: see downgrade, 158 
destination: branch statement, 179 
destination of branch with action C: caution, 114 
determinant of a matrix, 166 
devices: irrelevant to APL language, 10 
diagonal: extracted by mapping two or more axes 
together with dyadic transpose, 145 
dialogue: interactive computing resembles, 5 8 17 
diamond: branch in line that contains, 180 
portion of line executed when error encountered, 
278 
to permit test and sensitive code to be executed 
in same line of secure function, 103 
to separate multiple statements within a line, 16 
17 21 170 
trace of line containing, 210 
trap line may contain, 114 
difference: Arithmetic, 128 
different names: partners may share, by using surro- 
gate, 89 
DIGITS: control message mnemonic for DPP, 82 
)DIGITS, former command, 264 
digits: more requested than system can supply, 178 
number of significant, 52 53 82 172 173 235 261 
262 264 266 
dimension: see axis, 13 
direct definition: examples, 33 
way to get function definitions, 36 
directory of user account numbers, 2 7 
display: automatic, during T-task, 8 
automatic, evoked by (Js, 235 
automatic, when root function is ¢, 19 
automatic, when system supplies, 20 23 
function definition, 33 63 
omitted, during “terse” use of line editing, 67 
timing and width with M, 236 
distinct elements: expression, 154 
distinction between a number and its representation, 
160 
Distinction between APL language and APL sys- 
tem, 10 
Distinguished name, 28 
distinguished name: localization, 38 
may not be shared, 89 
to denote a primitive function, 14 
used for system functions and system variables, 
27 40 
distinguished names: key to classification, 30 
distinguishing user entries from system responses, 5 
62 
distribution of random numbers, 126 


Division, 129 
division: identity element, 187 
matrix, 165 
division by zero, 129 
Divisions of a line: label, body, comment, 17 
domain: function’s, 12 30 
see entry for the particular function whose do- 
main is desired 
DOMAIN ERROR, 280 
example of error reflecting inappropriate use of 
data, 109 
following inappropriate use of QPDEF, 247 
following inappropriate use of OPVAL, 247 
trappable event, 110 166 
domino: see “matrix divide” and “matrix inverse,” 
165 
dot: signals terse form during two-pass line editing, 
67 68 265 
to indicate “null” left argument of dyadic opera- 
tor, 14 22 27 189 190 
dot-comma editing, 64 265 
see “line editing,” 5 61 62 64 66 67 68 69 71 
262 265 
dot-matrix printer: terminal using, 4 
Downgrade, 158 


Drop, 152 
drop: components from beginning or end of a file, 
100 


figure to illustrate, 153 

function that forms an array, 47 
Drop file components: description of [DROP, 217 
)DROP system command, 267 
Dual use of function symbols, 19 25 
duration of file tie, 87 101 
duration of sharing, 87 
dyadic function: definition, 19 25 

implied when preceded by an expression, 21 
Dyadic operator, 188 
dyadic operator: arguments, 22 

examples, 14 
Dyadic scalar function, 128 
dyadic scalar function: applicable operators, 46 
dyadic transpose, 145 


E 


e: base of natural logarithm, 125 
E: exponential format with QFMT, 202 
in exponential representation of a number, 15 52 
177 
E action: cause system to execute trap line, 114 
caution regarding destination of branch, 114 
effect of trap line, 118 


trap line, 232 
e to the x: see exponential, 125 
editing, function, 2 36 38 39 61 63 64 66 71 204 
205 206 278 
comparable forms with [FD and (CR, OFX, and 
DEX, 205 
del editor, 36 63 
restriction when function already exists, 63 
effect: distinguished from result, 32 
Effect of permission codes on use of file func- 
tions, 102 
elapsed time: reported by QRUNS, 198 
element of an array: each is single number or single 
character, 44 45 
Elementary Analysis: text by K.E. Iverson, 137 
138 
element-by-element application of a dyadic scalar 
function to array arguments, 46 
elements: total number in array, 46 
elements of an array: function applied to all, 2 
elements of an array constant: how separated, 51 
elided left argument of a defined function, 21 
Empty array, 47 
empty array: display, 47 
type, 47 
empty axis: expand applied to, 158 
minimum, 134 
reduction over, 186 
take applied to, 153 
empty branch: meaning, 42 
response to request for [] input, 239 
empty line: DFD condition, 207 
empty (TRAP: more global (TRAP supersedes, 113 
empty statement, 17 
empty vector: argument of (SVQ, 252 
displayed differently from empty array of other 
rank, 53 
effect of branch to, 180 
result of 10, 154 
Encode, 160 
encode: algorithm, 163 
one way to generate explicit representations, 49 
encoding: ASCII, general description, 76 
IBM, general description, 77 
transmission between system and terminal, 74 
239 
endless loop: uninterruptable if D7RAP set improper- 
ly, 119 
ceiencaneets in SHARP APL, v 
enter: to complete a line by pressing RETURN, 17 
enterable characters, 54 57 59 
argument of ¢, 171 
entry: maximum length from keyboard, and with 
DARBIN, 262 
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non-responsive, following request for J input, 238 

entry, data: see also character input, evaluated 
input, arbitrary input, O or 0 

Entry and display of data arrays, 51 

Entry or display of unrecognized characters, 54 

environment in the active workspace: Reporting 
the, 40 

environment of computation: way to conceive sys- 
tem, 10 

EOT: signal marking end of transmission from 
IBM terminal, 240 

Epsilon, 159 


Equal, 135 
equal: effect of comparison tolerance, 121 135 154 
159 259 


identity element, 187 
meaning and precedence distinguished from uses 
in conventional algebra, 24 
“equal”: tolerant (i.e. fuzzy) comparisons, 121 
equations: set of linear, 166 
erase: function to free visible use of name, see “ex- 
punge,” 207 
Erase file, 216 
)ERASE system command, 268 
compared with system functions, 207 
effect on shared variable, 87 
treatment of package, 245 
use of groups, 37 
when object erased is a group, 294 
error: correcting function definition, 36 
correction, 5 
effect on file hold, 220 
event number between 1 and 499 indicates, 109 
immediate notification, 5 
in defined function forced by DSIGNAL, 117 
return to immediate execution following un- 
trapped, 62 107 
test by using [SIGNAL to simulate, 118 
error message: bypassed by use of DTRAP, 117 
form, 278 
form when error is in argument of 2, 171 
not affected by DOUT parameter, 80 
point of view, 278 
source, 277 
user defined, generated by OSIGWAL, 107 109 
when there is no valid (PW, 262 
Error messages and trouble reports, 277 
error trapping: see “event trapping” 
Errors list, 110 
ESCAPE: character transmitted from terminal but 
ignored, 56 
terminal control key, 54 55 
escape sequence: ignored because of TRAP, 119 
in response to [ input, 73 237 


321 INDEX 


in response to request for [] input, 72 
input, 55 69 72 119 282 283 
Evaluated input: description of 4], 238 
Evaluated input mode, 72 
evaluated input mode, 41 61 72 115 180 235 238 
239 240 262 263 
trap for return to immediate execution does not 
include, 115 
evaluation of an expression: discussion of general 
meaning in mathematics, 12 
evaluation of tree structure proceeds from leaves to 
root, 19 
evaluation order: arguments of a dyadic function, 24 
contrasted with conventional algebra, 23 24 
effect of parentheses, 23 
functions within statement, 22 
operators, 22 
operators vs. functions, 21 
statements within a line, 17 21 
evaluation statement (one of two classes of state- 
ments), 18 
even parity: terminal transmission codes, 77 
even root: undefined for negative value, 129 
event number: identifies trappable event, 108 109 
field within trap definition, 108 111 113 232 
first line of QER always contains, 108 109 
following DSIGNAL, 117 
part of event report, 231 
event numbers 0, 1000, 2001: special significance in 
trap definition, 110 
Event report: description of DER, 231 
event report: diagnosis of event and selection of re- 
medial action, 108 
system variable containing description of most re- 
cent event, 107 109 233 
Event reporting, 108 
event title: field within event report, 108 109 233 
system default, with monadic use of SIGNAL, 
109 233 
Event trap: description of OTRAP, 232 
Event trapping: system function and variables, 
231 
event trapping: Building and using functions, 
117 
event trapping: outline of facilities, 107 
situations in which useful, 106 
event 1001: stop, 111 209 
event 2001, 110 111 115 116 197 232 
event 67, 285 
event 67 68: effect on DER, 232 
event 68, 286 
events: trappable, classification, 107 109 
Events that are reported but not trapped, 111 
Events that can’t be trapped, 116 


f “except”: action S in trap definition, 115 
exclusive or: denoted by z, 134 
Exclusive tie, 212 
exclusive use of a file: file hold contrasted with ex- 
clusive tie, 220 
requested by file-hold function, 219 
Execute: definition of primitive function, 170 
execute: aborted by SIGNAL, 233 
automatic display of result, 171 
automatically invoked at load for DZX, 259 
branch in argument compared with branch in 
trap definition, 114 
compared with 6 [WS, 229 
form of error message describing error, 171 
meaning of +0 and >10 in argument, 171 
represented in state indicator and line counter in 
same manner as a defined function, 41 223 
259 
execute within trap line: trappable error, 114 
executed: position of line before error encountered, 
278 
execution: Order of functions within statement, 
22 
Order of operators, 22 
Order of operators and functions within a 
statement, 21 
Order of statements within a line, 17 21 
execution: aborted by action C in trap definition, 
114 
aborted by naked branch, 179 
aborted by OSIGNAL, 107 233 
aborted by trap action C, 113 114 118 232 
automatically resumed with QTRAP, 117 
conditional, 180 
line is minimum requestable unit, 17 
order reflected in tree diagram, 19 
resumption following “stop,” 209 
resumption of suspended or pendent function, 41 
179 
suspension following error, 5 
execution mode: see immediate execution mode 
execution of a defined function: sequence of events 
when system starts, 43 
EXIT: to force exit from function with trap action 


D, 116 232 
exit from function: consequence of branch statement, 
179 
possible action in response to event 2001, 110 116 
232 
Expand, 157 


expand: fill element, 47 158 
function that forms an array, 48 
perhaps an operator?, 14 
subject to axis operator, 188 


explicit argument and result: required to use defined 
functions in phrases, 32 
Explicit control of transmission codes, 55 
Explicit control of turn-around, 78 
exponent: negative, in number representations, 52 
177 
Exponential, 125 
exponential and decimal fields in same display: 
dyadic ¥, 178 
exponential format: with dyadic ¥, 173 177 
with FMT, 202 
exponential or decimal form: how system selects, 53 
selection with dyadic ¥, 175 
exponential representation, 52 
Exponentiation, 129 
exponentiation: no precedence over other functions 
(such as multiplication), 24 
expression: definition, 18 
evaluation of yields result, 13 18 
left argument of function, 23 
may lack result, 18 
minimal, may be a single variable or a constant, 
19 
requires defined functions that accept explicit ar- 
guments and return explicit results, 32 
Expressions, 18 
expressions: several, in a list, 48 
Expunge: description of [EX and DFD, 207 
expunge: consequence of use of [PDEF, 247 
effect on shared variable, 87 
Expunge names from package: description of 
OPEX, 248 
extension: scalar, with dyadic scalar functions, 128 


F 


F: fixed-point format with DFMT, 202 

Factorial, 125 

failure: equipment, safeguarded by archiving of 

files, 10 

Falkoff, Adin D., iv 

false: result of Boolean function, 134 

Family of circular functions, 135 

field: character data treated as numeric, 200 
formatting numeric data, 53 
separated from adjacent, with dyadic ¥, 176 

field overflow, 178 203 

field width: dyadic ¥, 173 176 
insufficient, 178 
minimum required for exponential display, 177 
system-default displays affected by QPP, 53 
system-default numeric displays, 53 

field width zero lets system pick width, 174 
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file: access matrix, 102 
append component, 213 
archive copies maintained daily, 10 100 
control information, 9 100 231 
data usable only while in active workspace, 6 
erase, 216 
identifying which you’re talking about, 101 
library number, 99 215 
name and account number, 9 99 102 211 214 215 
219 267 
owner, 99 
owner excluded from access, 219 
primitive functions, 9 99 211 
public, 99 211 
read a component, 214 
replace a component, 214 
shared, 9 10 85 99 101 212 219 220 
temporary exclusive use with file-hold functions, 
219 
terminal output appended to, 241 
tie, 212 
untie, 213 
file: Appending normal output, 79 
File access control, 102 
FILE ACCESS ERROR, 280 
file cannot be tied with passnumber given, 104 
trappable event, 110 
while DOUT in use, 80 
File availability: description of DAVAIL, 211 
FILE BACKUP INTERRUPT, 280 
file backup interrupt: trappable event, 111 
file component: each contains an APL object, 3 9 
100 
identified by its sequential position, 99 
number of first, 100 
size reported by DRDCI, 219 
FILE COMPONENT DAMAGED, 280 
trappable event, 110 
file component information: see “file control infor- 
mation,” 214 
FILE DAMAGED, 280 
trappable event, 110 
FILE FULL, 280 
example of event reflecting lack of space, 109 
trappable event, 110 
while DOUT in use, 80 
File functions and permission codes table, 218 
File hold: description of DHOLD and DFHOLD, 219 
file hold: caution against using data entry during, 
220 
conflicts during concurrent use, 9 10 219 220 
file index: effect of ODROP, 217 
valid, indicated by SIZE, 216 
FILE INDEX ERROR, 214 217 281 
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trappable event, 110 
FILE INTERRUPT, 281 
File library: description of OLIB, 211 
file library: public, 99 
file limit: see file quota, file tie quota, file reserva- 
tion 
file maintenance, 100 280 
file name, 99 215 
FILE NAME ERROR, 281 
trappable event, 110 
file quota, 101 216 
FILE QUOTA USED UP, 281 
trappable event, 110 
file reservation: effect of DERASE, 216 
element of result of OSIZE, 216 
limit after which nothing further can be stored 
until file resized, 101 214 215 
FILE RESERVATION ERROR, 215 281 
trappable event, 110 


} file reservations: Limit on total, 101 


file space: causes of variation in amount required, 
100 
File system, 99 
file system: provides auxiliary storage, 3 99 
FILE SYSTEM ERROR, 281 
trappable event, 110 
File system independent of APL interpreter, 105 
281 
FILE SYSTEM NO SPACE, 281 
trappable event, 110 
FILE SYSTEM NOT AVAILABLE, 281 
` example of event beyond user’s control, 109 
trappable event, 110 
FILE SYSTEM TIE CAPACITY EXHAUSTED, 281 
FILE SYSTEM TIES USED UP, 212 
trappable event, 110 
FILE SYSTEM UNAVAILABLE, 105 
File tie: description of Q7IE and QSTIE, 212 
file tie: duration, 87 101 
duration compared with duration of shared varia- 
ble coupling, 87 101 
following )CLEAR, 266 
not carried into split-workspace N-task, 101 
not recorded following premature termination of 
a task, 101 
not recorded in saved workspace, 273 
unaffected by changes to active workspace, 101 
FILE TIE ERROR, 281 
reference to untied file, 213 
trappable event, 110 
while DOUT in use, 80 
file tie number, 101 
file tie numbers: description of ONUMS, 211 
file tie quota, 110 212 281 


FILE TIE QUOTA USED UP, 212 281 
PILE TIED, 282 
trappable event, 110 
FILEAID workspace, 212 219 227 
Files, 9 
System functions for managing, 211 
files: tied, names and numbers, 211 
FILES UNTIED, 282 
fill element: used with take and expand, 47 48 158 
first positions: positive left argument of take, 153 
first-axis compress, 157 
first-axis expand, 157 
first-axis reduce, 185 
first-axis reverse, 142 
first-axis rotate, 143 
first-axis scan: symbol, 182 
first-axis summation: example produced by axis op- 
erator and reduction operator, 13 
Fix function definition: description of [FX and 
OFD, 206 
fixed point, 173 202 
floating point: internal data type, 288 
see also exponential representation 
Floor, 126 
FLOOR: defined function to show effect of DCT, 127 
floor: effect of OCT, 122 126 
)FNS system command, 268 
comparison with DNZ 3 and 1 [WS 1, 268 
folding of output line: how numeric display differs 
from character display, 262 
forced end: see “bounce,” 198 
Form numeric input: description of OFZ and (VJ, 
200 
Form of data storage in a file component, 100 
Form of QTRAP, 111 
Formal definition of “equal” and “not equal,” 
122 
Format: description of OFMT, 201 
FORMAT: control message mnemonic for [FMT out- 
put, 82 
FORMAT ERROR, 282 
trappable event, 110 
Format of access matrix: file, 102 
format phrase: within left argument of DFMT, 201 
formatting: preferable alternative to mixed output, 
49 
semicolons, 15 16 48 
FORMS CONTROL: HSPRINT control message, 82 
Forms in which operators, functions, and data 
may appear, 14 
fraction: problems in representing precisely, 53 
representation, 164 
fractional powers of negative arguments, 129 
free: result of DEX indicates which names are, 208 


freeze clone ID, 88 254 255 
FTT: function to convert QRDCI timestamp to con- 
ventional form, 219 
full interlock: shared variable, 96 255 
function: active, may not be erased, 268 
arguments passed by value, 19 
as argument of an operator, 13 
defined, aborted by use of OSIGNAL, 117 
defined, as class of use of a name, 37 38 223 224 
229 
defined, how arguments are written, 18 
defined, when used must be present in active 
workspace, 8 
derived, returned as result of an operator, 13 
discussion of term as used in mathematics, 11 12 
30 
exit from as consequence of branch statement, 
179 
how written with its arguments, 18 
object within a package, 244 
representation, 33 103 204 205 
root or principal, 18 
summary of forms in which it may appear, 14 
suspended, effect on line editing, 71 
suspended, resuming execution, 41 
syntactic class within a statement, 11 18 
system: see “system function,” or entries begin- 
ning with Q (alphabetized as if spelled 
QUAD) 
validity not checked during function definition, 63 
function definition: System functions, 204 
function definition: alternative means, 63 
system functions, 36 
Function definition mode, 63 
function definition mode, 61 
del signals, 63 
ended by final V or ¥, 64 
entering from immediate execution mode, 62 
marked by bracketed line number at start of each 
line, 63 
function display: various forms, 33 
function editing, 2 36 204 
always refers to global use of name, 39 
comparable forms with DFD and (CR, OFX, and 
DEX, 205 
difference between [JFD and OFX treatment of ex- 
isting function, 206 
limited to one function at a time, 63 
trouble report, 278 
using del form, 36 
function header: specifies syntax of a defined func- 
tion, 35 
function in a saved workspace: use obtained by load- 
ing or copying, 35 
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function name: not considered local to itself unless 
explicitly repeated in function header, 43 

function symbols: Dual use, 19 

function table: formed by outer product, 190 

Functions, derived functions, and operators, 13 

functions: Dyadic scalar, 128 

functions: Monadic scalar, 124 

functions: Non-scalar primitive, 140 

Functions and data, 11 

Functions and programs, 30 

Functions list: description of )FNS, 268 

functions selected by left argument of 0, 136 

Functions subject to DCT, 121 

Functions that form arrays, 47 

functions that use event trapping: Building and 
using, 117 

functions whose execution has not been completed: 
list, 41 

functions within a statement, Order of execution, 
22 

fuzz: see comparison tolerance 

fuzzy: see tolerant 


G 


G: picture format with QFMT, 202 
Gamma function, 125 
general arrays: see nested arrays 
General logarithm, 129 
general offer: shared variable, 86 
Global and local use of names, 38 
global function: created by del editor, 38 204 
global name: effect of )COPY command, 239 
erasure, 207 
shadowed by local name during function execu- 
tion, 43 
global object: definition, 38 
system commands )COPY, )PCOPY, )GROUP, 
and )ERASE, 39 
global DTRAP: may be effective even when shad- 
owed, 113 
precaution while developing new application, 118 
global value of system variables in clear workspace, 
42 266 
Grade, 158 
Greater than, 135 
greater than: identity element, 187 
Greater than or equal (not less), 135 
group: class of use of a name, 37 223 
Group members: description of 3 WS, 227 
)GROUP system command, 293 
Groups, 293 
)GRP system command, 293 
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)GRPS system command, 293 
gudermannian, 138 


H 


half duplex: setting of shared variable access control, 
96 
halt: in response to error or interrupt, may be 
trappable, 106 117 
halted work: possible to resume execution subse- 
quently, 8 
header: entered when opening definition of new 
function, 63 
semicolons, 15 
specifies local use of names, 38 
where syntax of defined function is specified, 34 
35 
hexadecimal: encoding and decoding number repre- 
sentations, 161 
representation of APL characters, 59 
hierarchy: APL has none, 22 
unexpected consequence of absence, 23 
highspeed printer: GOUT in preparing files, 80 
“highwater”: effect of max-scan, 185 
hold: file, conditions that terminate, 220 
file, to avoid conflicts during concurrent use, 9 10 
219 220 
HOLD: used with )OFF or )CONTINUE system com- 
mand, 270 
Hold files: description of HOLD and QFHOLD, 219 
hopper: function conceived as, 19 
Horizontal tabs: description of DHT, 251 
horizontal tabs: interpreted by system variable DAT, 
55 
host system: source of certain messages, 277 
hour: element of DTS, 224 
housekeeping: controlled more by system commands 
than by APL primitives, 10 263 
How a defined function receives its arguments, 
35 
How a shared variable permits communication, 
85 
How interruptions are handled when you are 
NOT trapping them, 107 
How sharing is initiated, 85 
How system locates the relevant trap definition, 
112 
How system selects permission code from file ac- 
cess matrix, 103 
HSPRINT: DOUT to capture terminal output, 80 
Hyperbolic functions, 139 
hyperbolic functions, 136 
figure, 138 


hyperbolic sine, cosine, tangent, cotangent, secant, 
and cosecant, 136 138 139 
hypotenuse: Pythagorean functions, 137 


I 


I: integer format with OFMT, 202 
IBM BCD code, 74 
IBM correspondence code, 74 
IBM encoded terminal, 239 
IBM encoding, 240 
general description, 77 
reported in 2 [WS 3, 227 
table, 75 
IBM implementation of APL, iv 
IBM manual: APL Language, v 93 
IBM terminal, 264 
explicit control of turn-around, 78 
keyboard locking on 2741, 268 
IBM2741: argument or result of )TERM command, 
274 
ID: variable in workspace 1 WSFNS, 56 
IDENTIFICATION IN USE, 282 
message relating to use of shared variable, 88 90 
255 
trappable event, 111 
identification of user: account number, 2 7 8 21 102 
212 214 226 227 242 252 269 272 276 
Identifying the operators within a statement, 22 
Identifying which file you’re talking about, 101 
identity element: dyadic scalar functions having 
none, 186 
reduction along axis of length zero, 186 
table, 187 
identity matrix, 165 
idle: character that can be displayed but not entered, 
56 60 
counted as character during transmission, 223 
must be explicitly transmitted in arbitrary 1/O 
to terminals, 79 
number calculated automatically except during 
arbitrary output, 79 
“if”: effect with conditional branch, 180 
ill-conditioned matrix: difficulty of inverting, 166 
illegal overstrikes during line editing, 71 
illumination: comment intended to provide, 17 
Illustrative programs for an N-task with multiple 
users, 97 
immediate batch, 5 196 
immediate correction of error, 5 
immediate execution: compared with execution of 
trap line, 114 
effect of OSIGNAL during, 233 


effect on file hold, 220 
return causes display of pending [" buffer, 236 
return to, as trappable event, 108 110 232 
return to, following error or interrupt, avoided 
with DTRAP, 107 111 
immediate execution line: preceding, captured as 
part of function definition, 64 
Immediate execution mode, 61 62 
imprecisions of representation: effect on sys- 
tem-default display, 53 
IMPROPER LIBRARY REFERENCE, 282 
following attempt to use )LIB or )SAVE com- 
mand, 273 
incidence map: A.= inner product, 50 193 
incoming offers: shared variable, 89 252 
incoming offers: Inquiring about, 89 
INCOMMUNICADO, 282 
following attempt to send message, 268 270 
INCORRECT COMMAND, 282 
INCORRECT SIGN-ON::, 282 
following attempt to sign on, 264 
indent: six-space, in continuation line of display, 
236 
six-space, marks immediate execution mode, 62 
six-space, not used with {f input, 73 
six-space, used to distinguish user entries, 5 
independent processors: modelled with shared varia- 
bles, 85 
Index, 154 
index: file, valid indicated in OSIZE, 216 
function that forms an array, 48 
INDEX ERROR, 282 
example of event reflecting inappropriate use of 
data, 109 
indexed assignment, 170 
trappable event, 110 
Index generator, 154 
Index of, 154 
index of: effect of OCT, 154 
effect of DIO, 154 
Index origin: description of OIO, 260 
index origin: description of index generator, 154 
global value in clear workspace, 42 266 
list of functions affected, 260 
tab stops, 251 
indexed assignment: rank and shape of arguments, 
170 
Indexing, 155 
indexing: figures illustrating, 156 
inapplicable to package, 245 
left argument does not require parentheses, 21 
155 
list indicates positions on successive axes, 48 155 
semicolons, 15 16 155 
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shape of result, 156 
inequalities: effect of OCT, 122 
inequality: Propositions on, 135 
infinity: minimum over an empty axis, 134 187 
negative, as result of maximum over an empty 
axis, 134 187 
infix: function of two arguments written as, 18 
inhibit action that would leave state vector un- 
changed: access control, 93 
inhibit use or set of shared variable: access control, 
92 
inhibited reference to a shared variable: attempting 
to carry out, 95 
delay interrupted from keyboard, 95 
initial value: empty array, 47 
OLX, 259 
initial value of shared variable, 87 
initials: account name, 271 
initiation of sharing, 85 
Inner product, 191 
inner product: compared with ordinary matrix 
product, 193 
figure illustrating, 193 
formed by product operator, 14 27 
significance of axes of an array, 49 
inner product and outer product: comparison, 192 
input: restriction on length of M, 237 
input/output: System functions, 234 
input/output translate table: reported by 2 [WS 3, 
227 
INPUT INTERRUPT, 282 
trappable event, 111 
input processor: source of certain messages, 277 
Inquiring about incoming offers, 89 
Inquiry (shared variable): description of OSVQ, 
253 


insert: block of characters during two-pass line edit- 
ing, 67 
characters during two-pass line editing, 67 265 
line in function definition, 64 
Insert package: description of DPINS, 246 
insertion and deletions: simultaneous, during two- 
pass line editing, 68 265 
insertions: scattered, during two-pass line editing, 67 
265 
insufficient field width: overflow character, 178 
integer: internal data type, 288 
integer format: with dyadic ¥, 173 
with DFMT, 202 
integers: iota as function to generate consecutive, 
154 
Interactive and batch use, 4 
interactive program: input to, 32 
interface: shared variable equivalent to, 85 
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INTERFACE CAPACITY EXCEEDED, 282 
trappable event, 110 
INTERFACE QUOTA EXHAUSTED, 283 
trappable event, 110 
interlocked shared variable: assure effective shared- 
variable communication, 85 255 
caution regarding debugging, 95 
Internal data types, 288 
Internal environment of a function, 35 
internal type: automatic conversion independent of 
OCT, 290 
result of certain arithmetic and logical functions, 
289 
interpolating extra lines: function definition mode, 
64 
interpreter: APL, 2 105 278 
file system independent, 105 
messages arising from, 278 
interpretive execution: consequences, 2 
INTERRUPT, 283 
following keyboard interrupt, 95 
interrupt: any task by QBOUNCE, 198 
described according to activity in progress when 
it occurred, 110 283 
distinguished from attention, 55 
during [J entry, 237 
effect of file hold, 220 
effect on use of OSC, 257 
event number, 110 283 
impossible to signal, with SIGNAL, 110 
intercepted by [TRAP for convenience or security, 
107 
may be unable to halt function that uses (ITRAP, 
117 
return to immediate execution following un- 
trapped, 62 107 
signal from outside the workspace, 109 
special precautions when trapping, 119 
trappable event, 111 
Interrupt list, 111 
interruption: impossible part-way through system 
command, 263 
intersection of sets: expression, 159 
inverse: conditions under which encode and decode 
may be, 163 
inverse circular functions, 136 
inverse hyperbolic functions: algorithms exploited in 
evaluating, 139 
Inverse of a matrix, 165 
inverse permutation: for upgrade and downgrade, 
158 
invisible: object outside a function having same 
name as argument, result, label, or local 
name, 43 


Invoking batch work from an interactive task, 5 
iota, dyadic: index of array in reference vector, 154 
iota, monadic: consecutive integers, 154 

iteration: common form of branching to achieve, 180 
Iverson, Kenneth E., iv 33 137 138 


Joining two arrays: see “catenation” and “lamina- 
tion,” 149 

jot: see dot 

K 


K: formatting scale factor, 203 
key letter: within (FMT format phrase, 202 
Key to classification of distinguished names, 30 
key tops: to adapt terminal to APL, 4 l 
)KEYB system command, 268 
keyboard: ASCII APL, 5 
characters distinguished from character data and 
from abstract characters in APL language, 
54 
entering data, 51 
immediate execution of line from, compared with 
execution of trap line, 114 
Keyboard control: description of )KEYB, 268 
keyboard entry: RETURN terminates each, 17 
keyboard locked: to await reply to message, 270 
keying time: reported by DAT, 222 
keyword: field within trap definition for action D, 
111 


L 


label: class of use of a name, 37 38 223 224 
destination of branch statement, 179 
may not be shared, 89 
receives value at moment system starts executing 
a function, 43 
separated from line by colon, 15 16 
value reported by 6 DWS, 230 
label, body, comment: Divisions of a line, 17 
Laminate, 148 
laminate: arguments, 149 
examples, 151 
function that forms an array, 48 


subject to axis operator, 149 188 
lamp: symbol to separate comment from rest of line, 
15 16 
language and system are distinct, 2 10 
last axis: marked by axis operator, assumed by com- 
press, expand, reduce, scan, catenate, ro- 
tate, reverse, 142 143 157 182 185 188 
last positions: negative left argument of take, 153 
Latent expression: description of OLX, 258 
latent expression: avoid conflict between [TRAP and, 
119 
following use of QZOAD or [@LOAD, 243 
global value in clear workspace, 42 266 
to start N- or B-task, 197 
Lathwell, Richard H., iv 
leading decision: form of branch control, 180 
leading zeros: data entry and system-default dis- 
plays, 52 
OFMT display, 203 
least-squares solution of over-determined system, 
166 
left argument, 23 
parentheses required around expression, 21 
when may be omitted in use of defined function, 
21 
left arrow: see specification, 13 18 20 24 34 35 38 
168 169 170 172 210 
left identity, 186 
left-to-right execution of functions, 23 
LENGTH ERROR, 283 
example of event reflecting inappropriate use of 
data, 109 
trappable event, 110 
length of [ input: restriction, 237 
length of each axis: result of monadic rho, 140 
Less than, 135 
less than: identity element, 187 
Less than or equal (not greater), 135 
LF: variable in workspace 1 WSFWS, 56 
)LIB system command, 268 
librarian: system, custodian of public workspaces, 9 
library: file, 9 99 102 211 214 215 219 267 
set of saved workspaces belonging to an account, 
8 
library number: copied workspace, 266 
part of workspace identification, 276 
saved workspace, 269 272 
Library number of a file, 99 
LIBRARY TABLE FULL, 283 
limit: connect and CPU, for task started by ORUN, 
197 198 
Í file reservation, 216 
number of simultaneously tied files, 212 
} Limit on total file reservations, 101 
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Line: the unit of execution, 17 
line: Statements within, 17 
line: constant must be written as a single, 13 
distinguished from statement, 17 
if entered during immediate execution mode, is 
immediately executed, 62 
multiple statements separated by diamond, 16 
prompt and reply on same, 236 
Line counter: description of OZC, 223 
line counter: acquires new element when system 
starts executing a defined function, 43 
both active and saved workspaces include, 8 
contains zero where state indicator shows ¢ or D, 
41 
current line of each active function, 41 226 
entries removed from by action C in trap defini- 
tion, 114 
following )CLEAR, 266 
reset by branch statement, 21 23 
line drop: communications failure, 270 
Line editing: immediate execution and function 
definition, 64 
Line editing: summary description, 264 
Line editing with suspended functions, 71 
line editing, 5 61 62 64 66 67 68 69 71 262 265 
aborted by escape sequence 0 BACKSPACE U 
BACKSPACE T, 69 
diagram summarizing, 64 
effect of OPW, 262 
switch from immediate execution mode, 62 
within function definition mode, 61 66 
within immediate execution mode, 61 66 265 
line length: maximum, 262 
line next to be executed: branch controls, 18 
line number: in representation of function to be 
fixed, 206 
system prompt in function definition mode, 63 
line of entry, 5 17 
line turn-around: explicit control for IBM termi- 
nals, 78 
linear equations: solved by matrix division, 166 
linear independence: criterion for matrix inversion, 
166 
linear regression, 168 
LINEFEED: terminal key, 55 
to correct current entry line, 64 
linefeed: character that can be displayed but not 
entered, 56 60 
must be sent explicitly as part of new-line se- 
quence in arbitrary output to ASCII ter- 
minals, 78 
lines: number required in display of an array, 53 
LINES DOWN, 283 
example of untrappable event, 107 
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lines marked “stop” or “trace”: recording or modi- 
fying, 210 
list: argument of QFMT, 201 
separate expressions for formatting or indexing, 
16 
List of APL enterable characters, 56 
List of separators, 16 
List of workspaces in library: description of 
)LIB, 268 
Listing names visible at each level of the state 
indicator, 42 
lists and semicolons: Note about, 48 
literal text: within DFMT display, 202 
load: execution of latent expression, 198 243 269 
session variable survives, 242 
)LOAD system command, 269 
effect on session variables, 249 
effect on shared variable, 87 
execution of latent expression, 42 119 197 198 
243 258 259 266 269 
loading a workspace: System functions for, 242 
load-WS: field within argument of ỌRUN, 196 
Local and global use of names, 38 
local function: means of creating, 36 204 
local name: definition, 38 
effect on 5 [WS, 229 
expunging, 207 
not copied, 239 
sharing terminated by exit from function, 87 89 
local names: class of use reported by 5 [WS, 39 
during execution of a function, 35 
list for each level of state indicator, 274 
local names within a function’s definition: no need 
to know, 43 
local values of DTRAP: system considers, 39 
localization: each level of state indicator, 42 
distinguished names, 38 
dynamic, 38 
function’s own name, 38 
OLX, 259 
OSP, 250 
localized DTRAP: system searches through, 113 
LOCK: option with )KEYB command, 268 
Lock function definitions: description of DFD, 208 
Lock functions in package: description of JPLOCK, 
248 
lock keyboard, 268 
to await reply to message, 270 
locked function: effect of sealing workspace, 274 
event report generated during execution, 108 109 
233 
not copyable from sealed workspace, 274 
representation, 205 
signalled by ¥ as the closing character, 63 


to conceal passnumber, 103 
with stop or trace set, 209 
locked workspace: password, 226 242 266 269 272 
273 276 
procedure for dropping, 267 
Logarithm: arbitrary base, 129 
Logarithm: natural, 125 
logarithm: absence of identity element, 187 
Logical functions, 134 
Logical negation, 127 
logical relations: effect of OCT, 122 
look-up: use of A.=, 193 
loop: conditional and unconditional branches, 180 
endless and uninterruptable, risked by improper 
use of OTRAP, 119 
lower case: how transmitted and represented at 
IBM-encoded terminals, 77 


M 


M: leading decorator for negative value, 203 
Maclaurin series: inner product with alternating 
sum, 193 
magic number: file: see passnumber 
Magnitude, 125 
maintenance: file, 100 280 
manipulating packages: System functions for, 244 
mantissa: exponential representation, 177 
mapping: function, from domain to range, 11 
mapping together two or more axes with dyadic 
transpose, 145 
mark: to indicate terminal’s current mode, 62 
matrix: appending a new row or column to, 150 
array of rank 2, 45 
grading rows, 159 
matrix algebra: inner products to represent, 49 
Matrix division, 165 
matrix form of DTRAP, 111 
Matrix inverse, 165 
matrix inverse: example of function benefiting from 
event trapping, 106 
matrix product: use of +.x, 166 193 
Maximum, 134 
maximum: not subject to OCT, 134 
over empty axis, 134 
use of [/Y, 185 
maximum line length: normal input and arbitrary 
input, 262 
maximum value for DCT, 135 
McIntyre, Donald B., 33 
meaning attached to an axis, 49 


meaningful value: DIO, 260 
OPP, 262 
OPW, 262 
ORL, 260 
Mechanisms for creating and modifying defined 
functions, 35 
Members of group: description of 3 OWS, 227 
Membership, 159 
merge: application of grade and indexing, 159 
Mersenne prime: in random number generator, 260 
message: error, bypassed by use of DTRAP, 117 
error, generated by SIGNAL, 233 
sign-off, 270 
sign-on, 264 
terminal-to-terminal, 262 
MESSAGE LOST, 283 
indicating terminal-to-terminal message aborted, 
270 
message number: field of control message, 81 
millisecond: element of DTS, 224 
minicomputers: in Sharp network, 7 
Minimum, 134 
minimum: not subject to OCT, 134 
use of L/Y, 185 
minimum field width: exponential display, 177 
Minus, 128 
minus: identity element, 187 
monadic function: see negation, 125 
minute: element of DTS, 224 
misspelled name in package: caution, 246 
MIXED: control message mnemonic for mixed out- 
put, 82 
mixed-base number systems, 160 
mixed functions: see non-scalar functions 
mixed output: (obsolete) use of list, 49 
mnemonic: field of control message, 82 
Modes of interaction at a terminal, 61 
modifying and creating defined functions: mecha- 
nisms, 35 
modular structure: user-defined functions, 1 
modulo: see residue, 129 
modulus: negative, included in APL definition of 
residue, 130 
modulus: see residue 
monadic function: definition, 19 25 
implied when no left argument is stated, 21 
Monadic operator, 182 
monadic operator: examples, 22 
Monadic scalar function, 124 
monadic scalar function: rank and shape of argu- 
ment, 26 
MONITOR: illustrative program for an N-task that 
communicates with multiple users, 97 
month: element of DTS, 224 
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Moore, Roger D., iv 
)MSG system command, 269 
addressee found by )PORT command, 271 
)MSGN system command, 269 
multi-axis array: blank lines separate successive 
axes in display, 53 
no special name, 45 
multiple assignment, 24 169 
multiple linear regression, 168 
multiple users: Illustrative programs for an N- 
task, 97 
multiplication: identity element, 187 
precedence, 24 
requires function symbol and cannot be indicated 
by juxtaposition, 24 
multiplication: see product, 129 
multiplier: in random number generator, 260 
multi-way branch, 180 


N 


N: trailing decorator for negative value, 203 
N action: later trap definitions in same [TRAP ig- 
nored, 115 
trap line, 232 
naked branch: contrasted with )RESET command, 
272 
effect, 180 
in response to request for O input, 72 180 239 
trace display, 209 
name: Visible use, 39 
name: Well formed, 39 
name: arbitrary, to stand for a defined function, 12 
component of a file does not have, 100 
distinguished, 14 28 40 
file, 99 215 
freed by use of DEX, 208 
function, not considered local to itself unless ex- 
plicitly repeated in function header, 43 
interpreted as name of an object in the work- 
space, 63 
local use of within a function, 38 
maximum length, 39 
method of assigning to a variable, function, or 
label, 38 l 
object within a package, 11 244 
only one use visible at a time, 39 
possible referents in a workspace, 39 
reference to a variable causes system to supply its 
value, 13 
referent within a package, 48 244 


331 INDEX 


required for each object stored in a workspace, 


shared variable, 88 
surrogate, for shared variable, 89 
value assigned, 18 169 
visible use, 204 
visible use as variable or label prevents fixing 
with [FD or OFX, 206 
workspace, 226 266 
name of a character, 57 
name of a file, 9 
Nameclass: description of ONC, 223 
nameclass: comparison of reports of DNC and 
5 DWS, 229 
package, 245 
Nameclass at each level of state indicator: de- 
scription of 5 [WS, 228 
Nameclass of names in package: description of 
OPNC, 246 
NAMEFN: illustrative function to generate names for 
multi-user shared variable task, 98 
Namelist: description of ONL, 223 
description of 1 DWS, 225 
namelist: form of argument of function applied to 
list of names, 245 
names: alternative uses within workspace, 37 
different, shared by using surrogate, 89 
items within a package, 48 
localized during execution of a function, 35 
order in result of ONL, 224 
same surrogate, differentiated by modifying, 98 
sequence within package, 48 246 
workspace as environment in which they have 
meaning, 37 
Names in package: description of DJPNAMES, 246 
Names in workspace, 37 
Names of tied files: description of DAMES, 211 
names within package: nameclass, 246 
order, 246 
Nand: logical function, 134 
nand: absence of identity element, 187 
Natural logarithm, 125 
nearest integer: tolerant definitions of floor and ceil- 
ing, 123 
Negation (algebraic), 125 
Negation (logical), 127 
negative arguments and fractional powers, 129 
negative exponent: number representation, 52 
negative infinity: maximum over empty axis, 134 
negative integer: argument of dyadic !, 132 
negative modulus: included in APL definition of res- 
idue, 130 
negative numbers: how represented, 52 
negative one: argument or result of DSVN, 254 





negative residue, 130 
negative sign: distinguished from function “minus,” 
52 
space for, in result of ¥, 15 174 
negative value: leading or trailing decorator, 203 
representation in characters interpreted with QV I 
and DFI, 201 
representation in number system with positive 
radix, 164 
nested arrays, 44 
nested expressions, 18 
network: communications, 3 107 
pairwise sharing, 91 
new axis: joining along, with laminate, 48 
new page: HSPRINT control message, 82 
newline: must be sent explicitly in arbitrary output 
to ASCII terminals, 78 
terminal-control character, 76 
next line to be executed, 223 
niladic function: definition, 19 25 
implied when no arguments stated, 21 
niladic primitive functions, 19 
no message: option with )KEYB command, 268 
no referent: name within a package, 247 
NO SHARES, 283 
example of event beyond user’s control, 109 
trappable event, 110 
NO SPACE, 283 
NOCLEAR: function in workspace 1 WSFNS, 116 
node number: component of port number, 271 
nodes of a tree diagram: represent functions, 19 
non-associative function: reduction by, 187 
use in inner product, 193 
NONCE ERROR, 283 
trappable event, 110 
non-negative value: leading and trailing decorator, 
203 
non-responsive entry: following request for [] input, 
238 
Non-scalar primitive functions, 140 
non-scalar primitive functions: list, 26 
non-terminal task: description, 8 
Nor: logical function, 134 
nor: absence of identity element, 187 
normal termination of a function: local trap defini- 
tion cannot detect, 115 
normalization: in exponential display but not needed 
in input, 52 
NOT COPIED:, 283 
following use of command )COPY or )PCOPY, 267 
Not equal, 135 
not equal: “exclusive or,” 134 
identity element, 187 
NOT ERASED: , 284 


following attempt to use )ERASE, 268 
NOT FOUND:, 284 
following attempt to use )ERASE, 268 
not greater: identity element, 187 
see “less than or equal,” 135 
not less: identity element, 187 
see “greater than or equal,” 135 
NOT SAVED, 284 
following attempt to use )SAVE command, 272 
NOT WITH OPEN DEFINITION, 284 
Note about semicolons and lists, 48 
Note on row-major order, 142 
N-task: activity not reported by DAI, 222 
clone ID, 87 
included in DUZ, 224 
OLX to start, 258 
shared variable partner, 84 91 
system function to start, 196 
terminated by system error, 111 
unable to handle untrapped errors or interrupts, 
107 278 
value of session variable at start, 250 
nub: vector of distinct elements, 154 160 
NUL: variable in workspace 1 WSFNS, 56 
null: affects transmission but cannot be entered from 
the terminal, 56 60 
symbol used as placeholder for left argument of 
product operator, 14 189 
number: distinguished from representation, 160 
page, HSPRINT control message, 82 
NUMBER IN USE, 284 
number line, 129 
NUMBER LOCKED OUT OF SHARP APL SYSTEM, 
284 
still possible to send message to system operator, 
269 
NUMBER NOT IN SHARP APL SYSTEM, 284 
following attempt to sign on, 264 
still possible to send message to system operator, 
269 
number of lines required for display of an array, 
53 
number of symbols: reported by )SYMBOLS and by 
2 WS 3, 274 
number of users, 224 
Number representation, 52 
number system: to encode and decode numbers, 160 
Numbers of tied files: description of DWUMS, 211 
numeric data, 44 288 
cannot occur in same array as character data, 47 
Numeric input from characters: description of 
OFI, 200 
numeric output: effect of OPW contrasted with char- 
acter output, 262 
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0 BACKSPACE U BACKSPACE T: input inter- 
rupt, 282 283 
to abort line editing, 69 
see also “escape sequence,” 55 69 72 119 282 283 
in response to request for D input, 72 
escape sequence during input, 55 
ignored becaused of OTRAP, 119 
object code and source not distinguished, 2 
object stored in workspace must be named, 8 
odd parity: terminal transmission codes, 77 
)OFF system command, 270 
offer, Shared-variable: description of 0SVO, 254 
offers: inquiring about incoming, 89 252 
omega: symbol for argument in direct definition, 33 
one: length of axis of reduction, 185 
one-origin: see index origin or DIO 
One-pass line editing, 66 
OPEN QUOTE: message during input, 16 
OFD condition, 207 
open quote: not distinguished from close quote, 15 
OPEN QUOTE ERROR: not a trappable event, 117 
operating system: source of certain messages, 277 
operator: dyadic, arguments, 22 
left argument, 22 
summary of forms in which it may appear, 14 
syntactic class within a statement, 11 
takes function as argument and returns function 
as result, 13 18 
operator (system): to send message, 219 269 
operator assistance: owner excluded from access to 
own file, 105 
when owner excluded from own file, 219 
operator message: blocked by “no message” option, 
268 
operator messages: unaffected by DPW, 262 
operator sequence: in syntactic analysis of a state- 
ment, 22 
Operator, 27 
operator: Dyadic, 188 
operator: Identifying within statement, 22 
operator: Monadic, 182 
operator: Valence, 21 
operators applicable to dyadic scalar functions, 46 
)OPR system command, 269 
)OPRN system command, 269 
Or: logical function, 134 
or: distinguished from exclusive or, 134 
identity element, 187 
to combine access controls set by two partners, 92 
Order in which the arguments of a dyadic func- 
tion are evaluated, 24 
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order of axes: array elements to be raveled or re- 
shaped, 142 
order of execution: arguments of dyadic function, 24 
effect on precision of result of reductions, 187 
effect on precision of result of scans, 182 
order of execution: Universal application, 23 
Order of execution: functions and operators 
within a statement, 21 
Order of execution: functions within a statement, 
22 
Order of execution: operators, 22 
Order of execution: statements within a line, 17 
21 
order of names: result of DNZ, 224 
within package, 246 
origin: index, 42 154 157 188 260 264 266 
)ORIGIN: former command, 264 
Orth, Donald L., 33 
outer and inner product: comparison, 193 
Outer product, 189 
outer product: figure illustrating, 190 
formed by product operator when left argument 
is null, 14 27 
Outline of the trapping facilities, 107 
output: terminal, captured with DOUT, 79 241 
unwanted, suppressed by use of QOUT, 80 
output buffer: [], 236 
output parameter: OUT setting following )CLEAR, 
266 
output to file: Appending normal, 79 
over-determined system: matrix inversion and divi- 
sion, 165 
overflow: field, 178 203 
overstrike: apparent but not recognized if DARBOUT 
mixed with M, 238 
illegal, during line editing, 71 
merging character from prompt with character 
from response, 73 237 
method of forming certain characters for input or 


display, 54 
not resolved by the system during QARBIN input, 
74 


permissible in input, 57 
uninterpretable, rejected during input, 55 237 
over-take, 153 
owner excluded from access to own file: recourse, 
104 
Ownership of a file, 99 
ownership of a file: implicit last row of accesss ma- 
trix, 102 
in public library, 102 
powers implied, 99 
transfer, 215 
ownership of a task, 7 196 198 


P 


P: leading decorator for positive or zero value, 203 
Pack names: description of JPACK, 245 
Pack value: description of dyadic [IPACK, 246 
package: as data object, 11 244 
attempt to display, 235 
deciding whether variable is or is not, 245 
effect of packing function in which stop or trace 
is set, 210 
forming does not constitute use of shared variable, 
245 
function to form, 245 
names not represented in workspace symbol table, 
274 
source of defined functions, 36 
unnamed file component, 244 
Package insert: description of DPINS, 246 
Package structure, 48 
**PACKAGE**: message in lieu of display of pack- 
age, 235 245 
packages: System functions for manipulating, 244 
Packages and arrays, 44 
PAGE: control message mnemonic for HSPRINT new 
page, 82 
PAGEN: control message mnemonic for page number, 
82 
paradigm: provided by function header, 35 
parentheses: around list in right argument of DFMT, 
48 201 
around repeated phrases in left argument of 
OFMT, 202 
effect on order of evaluation of functions, 23 
not needed around expression within a list, 49 
redundant, 23 
type of delimiter, 15 
parenthesis: distinction between British and North 
American usage, 15 
right, first character of system command, 15 63 
263 
parity: terminal transmission codes, 77 
use of #/Y, 185 
parity bit: not represented in result of DARBIN, 77 
partial result: displayed by inserting Q+ in com- 
pound expression, 235 
partition matrix: inner product, 193 
partner: described by second and fourth elements of 
access control and state vector, 90 92 255 
with whom you share a variable, 84 
pass-by-value: arguments of a function, 43 
Passnumber: file, 103 
passnumber: file, 212 217 
in design of secure application, 103 
invalid if supplied when not needed, 104 


not used with QUNTIE, OCREATE, or DHOLD, 103 
user must supply, both to tie and to use, 102 
zero means “none required,” in file access matrix, 
102 
password: )CONTINUE workspace, 271 
sign-on, 264 271 
workspace, 226 242 266 269 272 273 276 
PATIENCE PLEASE, 284 
example of untrappable event, 107 
)PCOPY system command, 266 
compared with QPPDEF, 247 
during D input, 239 
when object copied is a group, 294 
pendent function: distinguished from suspended 
function, 41 226 
execution aborted by naked branch, 73 
state indicator, 41 226 
periodic nature of sine, cosine, and tangent, 137 
permission code: How system selects, 103 
Permission codes: effect on use of file functions, 
102 
Permission codes: table showing associated file 
function, 218 
permission code: additive since each is a power of 
two, 102 
functions user may execute with given file, 102 
implicit, for owner of a file, 103 
needed to tie a file, 213 
see also discussion of each file function, 100 219 
permutation: random: see “‘deal,” 178 
permutation matrix: inner product, 193 
permutation of axes: dyadic transpose, 145 
permutation vector: inverse, 158 
result of grade, 158 
phrase: within left argument of OFMT, 201 
pi: value, 126 
Pi times, 125 
Picking a name for a shared variable, 88 
picture format: DFMT, 202 
Placement of function’s arguments, 21 
plane of an array, 45 
Plus, 128 
plus: identity element, 187 
point: decimal, 15 52 174 177 202 203 
Point of view: state vector and access controls, 
90 
point of view: error message, 278 
polynomial: coefficients arranged along one axis, 49 
coefficients in number systems, 161 
evaluation with decode function, 165 
evaluation with inner product, 193 
polynomial approximation, 168 
port number: reported by )PORT command, 271 
reported by 2 [WS 3, 227 
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)PORT system command, 271 
to find task number of addressee of a message, 
269 271 
position values: radix of a number system implies, 
162 
Possible actions in the trap definition, 113 
Power, 129 
power: fractional, of negative arguments, 129 
identity element, 187 
precautions when trapping interrupts, 119 
precautions while working with DTRAP, 118 
precedence: operator higher than function, 21 
precision: dyadic ¥ and (FMT F format, 173 202 
interaction with order of execution of scans, 182 
see comparison tolerance OCT, 42 121 122 123 
126 127 131 135 154 159 259 266 290 
predictor coefficients: linear regression, 168 
prime: random number generator, 260 
prime factors: evaluation of numbers represented by, 
193 
primitive function: summary of forms, 14 
symbols to represent, 12 
system functions with names starting with 0, 12 
Primitive functions, defined functions, and pro- 
grams, 12 
primitive root: multiplier for random number gener- 
ator, 126 
primitives: operators exist only as, 14 
rich set, 2 
system functions considered as, 27 
principal function, 18 19 20 23 169 172 210 
print positions: number required for numeric dis- 
play, 173 
Print precision: description of DPP, 261 
print precision: effect on default display and monad- 
ic ¥, 42 53 172 266 
global value in clear workspace, 42 266 
Print width: description of OPW, 262 
print width: global value in clear workspace, 42 266 
see also entries under [JPW (alphabetized as if 
spelled QUADPW) 
printer, highspeed: batch job to print file, 3 
file prepared with DOUT, 80 
print-wheel: terminal using, 4 
private library: conditions under which another user 
may use, 8 
workspaces belonging to an individual user, 8 
processor: auxiliary, 91 
owner of active workspace with which you share 
a variable, 84 
Processor ID, 87 
processor ID: argument of SVQ, 89 252 
generating name based upon partner’s, 98 
result of OSVQ, 89 252 
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to offer to share a variable, must know partner’s, 
85 
PROCESSOR TABLE FULL, 284 
trappable event, 111 
product and quotient: Arithmetic, 129 
product of powers: evaluation by inner product, 193 
Product operator, 189 
product operator: instance of dyadic operator, 14 
scalar dyadic functions, 26 
product over: use of x/Y, 185 
program: connotation contrasted with that of “func- 


tion,” 31 
when used, must be present in active workspace, 
8 


programming: usage of term in APL community, 33 
Programs and functions, 31 
Programs, primitive functions, and defined func- 
tions, 12 
progressive sum, product, maximum, minimum, 185 
prompt: emitted with M+, merged with input in re- 
sult of <, 73 
emitted with DARBIN, control message, 82 
DARBIN compared with JARBOUT, 240 
separating from [ reply, 238 
prompted input: effect of DOUT, 80 
proposition: used to control compress and expand, 


Propositions on equality, 135 

Propositions on numerical inequality, 135 

Protective copy, 239 247 266 294 

Protective definition of names from package: de- 
scription of DPPDEF, 247 

PRTARBOUT: control message mnemonic for 
HSPRINT display of arbitrary output, 82 

pseudo-random number, 126 260 

public files, 211 

ownership, 102 

public function: obtained by loading or copying from 
public workspace, 35 

public library: restriction on use of )DROP, 267 

set of workspaces saved for use by others, 9 269 

272 

Public workspaces, 9 

publication form of function display, 33 

Punctuation, 15 

punctuation: syntactic class within a statement, 11 

Pythagorean and circular functions (figure), 137 

Pythagorean functions: members of class of O func- 
tions, 136 





Q 


Q: trailing decorator for positive or zero value, 203 
QUAD: entries beginning with D are alphabetized 
as if spelled QUAD 
QUADP: control message mnemonic for [ output, 82 
Q: considered as shared variable for input to a pro- 
gram, 32 
description of 1] input, 238 
entry on state indicator reflected in DZC, 223 
evaluation aborted by use of DSIGNAL, 233 
first character of distinguished name, 40 
represented in state indicator and line counter in 
same manner as a defined function, 41 
syntax, 234 
O and M: comparison of cursor position preceding, 
235 
D input: effect of branch during, 180 
system command, 263 
trap for return to immediate execution does not 
include, 115 
quad mode: short for evaluated input mode, 41 61 
72 115 180 235 238 239 240 
D or M: tracing statement containing output, 210 
Quad output: description of (+, 235 
O output: subject to DPW, 262 
QUAD PRIME: entries beginning with [ are al- 
phabetized as if spelled QUADPRIME 
DAT, 222 
DAPPEND and (APPEWDR, 213 
DARBIN, 239 
clears |) buffer, 73 
combined with use of OUT, 80 
control message in DOUT file, 81 
position of cursor at start, 235 
to receive arbitrary signals from terminal, 55 73 
234 
unaffected by DPW, 262 
OARBOUT, 239 
control message for, in DOUT file, 81 
control transmission codes to terminal, 55 234 
drawback in using to separate [ prompt and 
reply, 238 
unaffected by DPW, 262 
DAV: reference set of all 256 possible characters, 54 
159 
DAVAIL, 105 211 
OBOUNCE, 198 
effect on batch task, 197 
executes )CONTINUE command, 270 
impossible to trap, 117 
OCR, 205 
OCR and DFX: compared with DFD, 204 


OCREATE, 215 
OCT, 121 259 
does not affect minimum, 134 
effect on dyadic iota, 154 
global value in clear workspace, 122 259 266 
in definition of ceiling, 127 
in definition of floor, 126 


in definition of membership, 159 
in definition of residue, 131 
list of functions subject to, 121 259 
localization, 121 
maximum value, 135 259 
meaningful values, 122 
not involved in automatic type conversion, 290 
signum function unaffected, 124 
with = and #, 135 
zero, applications, 122 
OCT ERROR: see [xx error, 287 
trappable event, 111 
ODL, 259 
caution regarding delay in display at terminal, 
260 
comparison with QSC, 260 
DODROP, 217 
OER, 231 278 
does not record certain events, 117 
form, 108 
in trap line, 118 
in workspace following abnormal end of task, 117 
197 
record of stop control, 209 
set by use of OSIGNAL, 233 
short form when workspace lacks space to devel- 
op full report, 108 109 
OERASE, 216 
OFX, 207 
compared with FD, 204 
treatment of package, 245 
OFD, 205 
compared with [CR and DFX, 204 
means of naming a function, 38 
treatment of package, 245 
DFD ERROR, 207 
OFF, 291 
DOFHOLD, 219 
DFI, 200 
OFMT, 201 
control message for, in DOUT file, 81 
effect of [PW compared with its effect on default 
display, 262 
example with DOUT control message, 81 
list right argument, 48 
permits commas and other arbitrary characters 
within a number representation, 52 
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OFX, 206 
means of naming a function, 38 
OFX and OCR: compared with QFD, 204 
DHOLD, 219 
OAT, 251 
initial value in batch task, 197 
precedes execution of DLX, 269 
survives clear, 265 
survives load, 269 
to interpret use of TAB key from a terminal, 55 
DHT ERROR, 252 287 
DET error: trappable event, 111 
Do, 260 
global value in clear workspace, 266 
index origin, 154 
indication of axis, 157 188 
list of functions subject to axis operator, 260 
list of functions subject to index origin, 260 
meaningful values, 260 
replaced former system command, 264 
OO error: trappable event, 111 
OIO ERROR, 260 287 
DLC, 223 
branch to, in workspace saved during O input, 
239 
caution regarding branch to, 223 
global value in clear workspace, 266 
system function to report values of line counter, 


40 223 
OLIB, 211 
DLOAD, 242 


effect on session variables, 249 
requires appropriate QZX in workspace to be 
loaded, 258 
OLX, 258 
execution follows copying of session variables, 
258 
following use of (LOAD or Q@LOAD, 243 
to start N- or B-task, 197 
value in clear workspace, 259 266 
ONAMES, 211 
effect of )CLEAR, 266 
ONC: encoding compared with DPNC, 247 
treatment of package, 245 
ONC classes compared with those used by 5 DWS, 
223 
OWL, 223 
comparison with )FNS and )VARS, 268 
comparison with 1 DWS, 225 
treatment of package, 245 
OWL classes compared with those used by 5 [WS, 
223 
DNUMS, 211 
effect of )CLEAR, 266 
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DOUT, 79 234 241 
combined with use of DFMT, 80 
excludes message resulting from system com- 
mand, 263 
some possible applications, 79 
with batch task, 197 
OPACK: dyadic, 246 
monadic, 245 
with shared variable does not constitute new use, 
86 95 
OPDEF, 247 
restrictions on when it may be used to define a 
function, 36 273 
to re-create names and their referents from with- 
in a package, 48 
OPEX, 248 
OPINS, 246 
OPLOCK, 248 
OPNAMES, 246 
deciding whether variable is or is not a package, 
245 


OPNC, 246 
encoding compared with ONC, 247 

DPP, 261 
effect on displays with O and M, 235 
global value in clear workspace, 266 
meaningful values, 262 
replaced former system command, 264 
significant digits in system-default displays, 52 
significant digits with monadic ¥, 172 
value in clear workspace, 261 

OPP ERROR: see [xx error, 287 

OPP ERROR: trappable event, 111 


OPPDEF, 247 
M: considered as shared variable for input to a pro- 
gram, 32 

separating prompt from reply, 238 
syntax, 234 

me, 235 

M buffer: effect of using DARBOUT or DARBIN, 240 
output, 236 

[H display: width and timing, 236 

input, 237 


position of cursor at start, 235 
shape of result, 73 

M mode: see Character input mode, 73 

M output: control message for, in DOUT file, 81 
last line included in following [ input, 236 
subject to OPW, 262 

OPSEL, 248 

OPVAL, 247 
means to extract a value from within a package, 

48 


DPW, 262 
displays that are unaffected, 262 270 
distinguishes line editing from sign-on, 264 
effect on display of character data different from 
effect on numeric data, 172 
effect on displays with O and M, 235 240 
effect on timing of [| display, 236 
global value in clear workspace, 262 266 
meaningful value, 262 
numeric output contrasted with character output, 
262 
request to position cursor beyond, during line 
editing, 71 
OPW ERROR: see (xx error, 287 
OPW ERROR: trappable event, 111 
OQLOAD, 242 
effect on session variables, 249 
requires appropriate ZX in workspace to be 
loaded, 258 
ORDAC, 102 217 
ORDCI, 219 
basis of daily archiving, 100 
OREAD, 214 
ORENAME, 215 
OREPLACE, 214 
ORESIZE, 216 
ORL, 260 
global value in clear workspace, 126 260 266 
new value as side effect of ?, 260 
ORL ERROR: see (xx error, 287 
ORL error: trappable event, 111 
ORUN, 196 
ORUNS, 198 
Ose, 255 
comparison with ODL, 260 
delay until change in shared-variable state, 255 
state-change variable, 96 
value, 257 
LISIGNAL, 233 
to abort execution of user-defined function and 
signal a trappable error, 117 
to abort function invoked by trap line, 116 
to test for conditions not otherwise encountered, 
118 
OSIZE, 216 
range of valid file indexes, 214 
space to permit an append or replace, 214 
OSP, 249 
initial value in batch task, 197 
precedes execution of ZX, 258 269 
recommended uses, 250 
retrieval from saved workspace, 250 
survives clear, 265 
survives load, 242 265 269 


OSTAC, 102 217 
OSTIE, 212 
shared tie of a file, 101 212 
OSvc, 255 
to set or report access control, 92 
OSVN, 254 
to set new clone ID, 87 


OSVO, 254 


Ambiguous use, 90 

dyadic, requires clone ID, 87 

to inquire about degree of coupling, 86 254 

to make share offer, 85 254 

OSV@, 253 

Ambiguous use, 90 

requires clone ID, 87 

to inquire about incoming offers, 89 

to inquire what processors are offering to share, 
or what names a processor is offering, 86 

with state change variable, 96 


OSVR, 255 
to terminate sharing, 87 96 
OSVS, 255 
to examine current state of shared variable, 90 
with state change variable, 96 
OIE: exclusive tie of a file, 212 
to start use of a file, 101 


OTRAP: avoid conflict with OZC, 119 
default value provided while testing new applica- 
tion, 118 
effect of localizing, 108 
following certain events, system searches through, 
107 
form, 111 
in workspace at end of N-task or B-task, 119 197 
inoperative when CLEAROUT set, 116 
localized, search through multiple levels, 113 
localized with action C, 114 
matrix and vector forms, 111 
may override stop control, 209 
precautions in using, 118 
reset by system if not well-formed, 112 232 
system may use shadowed values, 113 
unable to intercept certain events, 107 
well-formed, 232 
with trace capability as part of its trap line, 118 
with trap line that sets new value for Q7RAP, 118 
DTS, 224 
DUL, 224 
QUNTIE, 213 
OVI, 200 
(WA: work area remaining in workspace, 37 40 224 
227 
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OWS, 225 

classes compared with those used by DWC and 
OWL, 223 225 226 229 

comparison with )FNS and )VARS, 268 

following load and following renaming of active 
workspace, 269 

shadowed uses of name, 113 

)SIV compared with 2 [WS 2, 274 

system function to report workspace environment, 


use in reporting class of use of a name at each 
level of state indicator, 42 
using 2 [WS or 4 [WS with shared variable does 
not constitute new use, 87 95 
(xx ERROR: class of error messages, 287 
qualifiers and decorators: QFMT, 202 
Quiet load: description of DQLOAD, 242 
quota: file reservation total, 101 
number of files a task may have tied, 212 
workspace, required to use batch task, 197 
quote: occurring as a character within a character 
constant, 16 
to delimit character constant, 15 16 
quote-quad: alternative name for M; see quad-prime 
Quote-quad output: description of Me, 235 
quotes: unbalanced, 16 207 
quotient and product: Arithmetic, 129 


R 


R: background text for DFMT display, 203 
R: message prefix indicating reply expected, 270 
radian measure: to express arcs, 137 
radix: encoding and decoding numeric representa- 
tions, 160 
mixed, 161 
scalar, 163 
ragged array: not directly supported, 46 
random integers: algorithm used to generate, 126 
permutation, 178 
repeatability, 260 
with replacement: see “roll,” 126 
without replacement: see “deal,” 178 
Random link: description of DRE, 260 
random link: effect of ?Y, 126 
global value in clear workspace, 42 266 
range of a function: algebra, 12 30 
rank: catenating arrays of same and of different, 150 
RANK ERROR, 285 
example of event reflecting inappropriate use of 
data, 109 
indexed assignment, 170 
trappable event, 110 
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Rank of an array, 45 
rank of an array: found as ppY, 140 
rank of result of monadic scalar function, 124 
rank 0, 1, or 2: name for array having, 45 
rank 1: name for array having, 45 
rank 2: name for array having, 45 
ranking: achieved with 44, 158 
rational approximation: fractional power of negative 
argument, 129 
Ravel, 148 
ravel: function that forms an array, 47 
read: no special function needed -for, when using 
shared variables, 85 
Read control information: description of ORDCI, 
219 
Read file access matrix: description of IRDAC, 217 
Read file component, 214 
real numbers, 124 129 288 
receive: no special function needed for, when using 
shared variables, 85 
Reciprocal, 125 
recovery from error: sequence of steps, 107 
recovery from error or interrupt: see event trapping 
rectangular distribution of random numbers, 126 
rectangular structure of data, 44 46 
recursive function: body of function invokes the 
same function unless own name is explicit- 
ly localized, 43 
Reduction, 185 
reduction, 27 
by circular function, 136 
derived function subject to axis operator, 188 
domain of derived function, 185 
empty axis, 186 
example to illustrate syntax of operators, 13 
monadic operator, 22 
redundancy: over-determined system, 168 
reference: term defined, and implication for shared 
variables, 86 
reference to a variable’s name: causes system to sup- 
ply its value, 13 
referent of a name: within a package, 48 
regression: linear, 168 
relational functions: effect of comparison tolerance, 
122 
inapplicable to package, 245 
remainder: see residue, 129 
remove line of function definition, 64 
Rename file, 215 
rename file: effect on ownership, 99 
repetition factor: left argument of QFMT, 202 
repetitions in left argument of dyadic transpose, 145 
Replace file component, 214 
replace line of function definition, 64 


reply: separating from [M prompt, 238 
reply expected: terminal-to-terminal message, 270 
Representation, 160 
representation: algorithm, 163 
arranging one axis of an array as an explicit, 49 
completeness, 164 
distinguished from number, 160 
Representation of numbers, 52 
Representing and converting data, 200 
reservation: limits size of single file, 100 214 215 
216 
limits sum of account’s file reservations, 216 
reserved name: in general, APL has none, 2 
SA and TA are only instances, 39 
)RESET system command, 272 
Reshape, 141 
reshape: function that forms an array, 47 
Residue, 129 
residue: effect of OCT, 131 
identity element, 187 
Resize file reservation: description of RESIZE, 
216 
respecification: expression in which variable is also 
used, 169 
responsibility to avoid unresponsive programs: au- 
thor’s, 119 
restartability: batch task, 8 
localization of OLX, 259 
result: branch statement does not have, 18 
discussion of general use in mathematics, 12 
display, 5 8 17 
display with s, 171 
distinguished from effect, 32 
explicit, as requirement in constructing phrases 
from defined functions, 32 
explicit, indicated by name and assignment arrow 
in header of defined function, 35 
explicit, when function execution ends, is value 
of variable identified in header, 43 
expression, 13 
expression that has none, 18 
function: see entry for the particular function 
whose result is desired 
monadic scalar function, 46 
operator’s result is derived function, 22 
partial, displayed by inserting [+ in expression, 
235 


required if expression is argument of function, 19 
system command has none, 263 
when ¢ returns, 171 
when root function is assignment, displayed with 
trace control, 210 
result and arguments of a defined function, alternate 
forms for, 34 


Result, shape and conformability: arguments of 
dyadic scalar functions, 128 
resume execution, 8 
by + in trap line or from keyboard, 179 
del editor facilitates, 36 
procedures, 108 
Resuming execution of the most recently sus- 
pended function, 41 
Retract share offer: description of OSVR, 255 
Retract shared variable offer, 96 
RETURN: response to request for D input, 72 
terminal key, 55 
terminates JARBIN input and is represented in 
result, 73 240 
terminates [ input but is not part of result, 73 
return: as character or as signal that line is com- 
plete, 17 
result of a defined function, 43 
return to immediate execution: causes display of 
pending [ buffer, 236 
effect on DER, 232 
special provision in event trapping, 110 
Reverse, 142 
reverse: function that forms an array, 48 
reversing half duplex: setting of shared-variable ac- 
cess control, 96 
revise: function definition, 38 64 204 205 206 
keyboard entry, 64 
Rho (dyadic), 141 
Rho (monadic), 140 
rho (monadic): returns shape of an array, 46 
right argument of a function, 23 
right arrow: first character of branch statement, 179 
in response to request for Q input, 72 
symbol for branch, 18 21 23 27 41 42 72 73 108 
114 171 179 180 209 223 239 272 
trace of branch taken, 209 
right identity, 186 
right parenthesis: first character of each system com- 
mand, 15 63 263 
to start sign-on, 264 
right triangle: Pythagorean functions, 137 
right-to-left execution of functions, 23 
Roll, 126 
roll: effect of ORZ, 260 
root: nth, see “exponentiation,” 129 
root function: result not displayed when assignment 
is, 169 
within an expression, 18 23 
Rotate, 143 
rotate: function that forms an array, 48 
subject to axis operator, 188 
rotation: cyclical, 144 
direction indicated by sign of left argument, 143 
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rotation of rank-3 array: example, 144 

rounding: see floor and ceiling, 121 126 127 

row: appending a new one to a matrix, 150 
selecting an entire one from a matrix, 155 

row of an array, 45 

Row-major order, 142 

row-major order: in ravel and reshape, 47 141 148 

Rules governing access matrix (file), 103 

Run: description of QRUN, 196 

Runs: description of DRUNS, 198 


S 


S: QFMT substitute for standard characters, 203 
SA: prefix indicating stop control, 208 
S action: part of trap line while debugging, 118 
to aid debugging, 115 
to halt error trapping, 115 
trap line, 232 
same line: prompt and reply, 236 237 
SATN (SHARP APL Technical Notes), vi 
save: automatic, of N-task’s active workspace, 197 
)SAVE system command, 272 
during [O input, 239 
following )LOAD command, 269 
result of 2 [WS, 226 272 
workspace full following attempt to use, 98 
saved workspace: command to drop, 267 
contains state indicator and line counter, 41 
data usable only while in active workspace, 6 
distinguished from active workspace, 8 
loaded for further use, 8 
retrieving DSP, 250 
updated by later version, 272 
saved workspace at end of N-task or B-task: avoida- 
ble with DTRAP action D, 116 
use of (TRAP, 119 
Saved workspaces, 8 
save-WS: field in argument of ỌRUN, 197 198 
scalar: argument of catenation, 150 
array of rank 0, 45 
produced by empty left argument of reshape, 141 
scalar extension: dyadic scalar functions, 128 
scalar function: Concept, 26 
scalar function: applying to all elements of an array, 
46 


definition, 26 
with operator to form scan, reduction, inner and 
outer product, 26 46 
scalar functions: Dyadic, 26 128 
Monadic, 26 124 
scalar radix, 163 
scale factor: OFMT K qualifier, 203 
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scan: derived function, order of execution, 182 
derived function subject to axis operator, 188 
monadic operator, 22 27 

Scan operator, 182 

scattered insertions: during two-pass line editing, 67 

265 

scheduler: B-task, 8 

Scientific Time-Sharing Corporation, iv 

)SEAL system command, 273 

sealed workspace: restriction on effects of )COPY, 

267 
restriction on use of DPDEF, 247 

secant, 137 

second: element of DTS, 224 

security: blot to obscure password, 265 271 
changing sign-on password, 271 
passnumbers to assure, 103 
prevent interruptions with QTRAP, 119 
[LX to initiate checks, 258 
seal workspace to prevent change or dispersal of 

contents, 273 
use of event trapping, 107 
Select names from package: description of DPSEL, 
248 

self-describing data, 1 21 47 288 
file component, 3 100 

semicolon: complete separator, 49 
not a function, 49 
to separate expressions within a list, 16 201 
to separate local names in function header, 16 38 

semicolons and lists: Note about, 48 

send: no function needed using shared variables, 85 

SENT: indicating transmission of — terminal-to- 

terminal message, 270 285 

separating [ prompt from [ reply, 238 

separation of adjacent fields: dyadic ¥, 176 

Separator: list, 16 

separator: class of punctuation, 15 
semicolon as complete, 49 

sequence: control in execution of a program, 180 
in concept of “program,” 30 

sequence in which statements are executed: branch 

modifies, 18 
Sequence of events when the system starts 
executing a defined function, 43 

sequence of names within a package, 48 

Serial editing, 68 

Session parameter: description of DSP, 249 

session variable: to pass information over load of 

new workspace, 242 249 
value at start of new task, 250 

Session variables, 249 

session variables: initial value in batch task, 197 
precede execution of OLX, 258 


survive )CLEAR command, 265 
set: first two positions in state vector and access 
control, 90 255 
term defined, and implication for shared varia- 
bles, 86 
set but not used: which shared-variable partner has, 
255 
Set clone ID: description of OSV, 254 
Set file access matrix: description of JSTAC, 217 
set membership: description, 159 
set of distinct members: expression, 154 
Set shared-variable access control: description of 
dyadic QSVC, 255 
set union, intersection, and nub: expressions, 160 
shadowed name: effective in system’s search for a 
trap definition, 232 
global use of name that is also used as argument, 
result, label, or local name, 38 43 
may still be shared, 88 
state change may involve, 257 
shadowed values of ỌTRAP: consequences of way 
system treats, 113 
system considers, 39 
Shape: monadic rho, 140 
Shape of an array, 46 
Shape of result and conformability of arguments 
of dyadic scalar functions, 128 
shape of result: monadic scalar function, 124 
M input, 73 
take and trop, 152 
SHARE TABLE FULL, 285 
trappable event, 111 
Share tie, 212 
shared file, 9 10 85 99 101 212 219 220 
shared files: shared-variable processor to manage, 85 
shared variable: access control, 92 255 
applications, 85 
delay calculated in advance using OSVS, 95 
delay reference to DSC until state change, 96 256 
duration of coupling compared with duration of 
file tie, 87 101 
effective sharing reported in result of dyadic 
Osvo, 255 
failure to use (but set instead), 95 
inclusion in package does not constitute new use, 
245 
initial value, 87 
interlocked, caution regarding debugging, 95 
interrupt during interlocked access, 110 
name, 88 
O or [M conceived as, 32 235 
reference inhibited, 95 255 
state, 92 255 
state transition diagram, 94 


state transition table, 93 
storage space for value, 98 228 
symmetry between partners, 90 
value reported by 6 [WS does not constitute new 
use, 229 
Shared-variable control, 92 255 
Shared-variable coupling: description of monadic 
OSVO, 254 
Shared-variable offer: description of dyadic OSVO, 
254 
Shared-variable query: description of SVQ, 253 
Shared-variable retract, 96 256 
Shared-variable state: description of OSVS, 255 
Shared variables for communication between 
workspaces, 91 
sharing variables: System functions for, 252 
SHIFT: represented in result of DARBIW from an 
IBM-encoded terminal, 77 
terminal key, 55 
SI DAMAGE, 285 
)SI system command: display of state indicator, 42 
71 
result of 2 (WS 2, 226 
side-effect: assignment gives new value to a variable 
as, 169 
signal: to request end of present mode or start of 
new mode, 62 
Signal event: description of DSIGNAL, 233 
Signalling a user-defined error, 117 
SIGNED OFF: following attempt to send message, 
270 285 
significance to particular axes: Assigning, 49 
significant digits, 52 53 82 172 173 235 261 262 
264 266 
controlled by OPP, 52 
dyadic ¥, 173 
maximum possible in system-default displays, 52 
178 
monadic ¥ controlled by OPP, 172 
Sign-off, 270 
sign-off: ends sharing, 87 
Sign-on, 264 
sign-on: field in argument of DRUN, 196 
immediate execution starts, 62 
Signum, 124 
simple array: restriction on current implementation, 
44 
simplex: setting of shared variable access control, 96 
Simultaneous deletions and insertions during 
line editing, 68 
sine, 137 
expression for Maclaurin approximation, 193 
selected by left argument of 0, 136 
single control pair applied to several columns, 175 
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single element: extension to array argument, 46 
singleton: see single-element array, 128 
singular matrix, 106 165 
sinh (hyperbolic sine): selected by left argument of 
o, 136 
)SIV system command: names localized within all 
active functions, 39 42 
six-space indent: marks immediate execution mode, 
62 
to mark continuation line, 236 
size of array: number of bytes of storage occupied, 
228 289 
shape, 141 
Size of file: description of OSIZE, 216 
size of file, 101 110 214 215 216 281 
size of symbol table, 224 227 266 274 
reported or set by )SYMBOLS command, 274 
size of workspace, 8 227 266 
reported by 2 [WS 4, 227 
skip to new page: HSPRINT control message, 82 
Some possible applications of DOUT, 79 
sorting: application of grade, 158 
file, as batch job, 3 
source and object code not distinguished, 2 
source of error messages and trouble reports, 277 
space: array storage may be changed by indexed 
assignment, 170 
available in workspace reported by [WA, 37 40 
224 227 
file, amount currently in use, 216 
file, causes of variation in amount required, 100 
Space reservations for files, 100 
spatial arrangement of data, 45 
Specification, 168 
specification: indexed, 169 
means of associating name with data, 38 
when root function, no automatic display of re- 
sult, 20 172 
speed of terminal, 264 
squish-quad: used as place-holder for undisplayable 
character, 54 
stack: see state indicator 
state: shared-variable, 255 
state change: events constituting, 257 
State-change signal, 96 
State-change variable: description of DSC, 255 
state-change variable: example, 96 
State indicator: description of )SI and )SIV com- 
mands, 274 
State indicator: reported by 2 [WS 2, 226 
state indicator: affects line editing while in immedi- 
ate execution with suspended functions, 71 
both active and saved workspaces include, 8 41 
clear, 180 272 
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damage, 285 
entries removed until level where relevant 
OTRAP was localized, 114 
following )CLEAR, 266 
function at top aborted by [ISIGNAL, 233 
list of active functions, 41 
names visible at each level, 42 228 
new entry when system starts execution of a 
function, 43 
DAC contains element for each row, 223 
(LX included, 259 
restriction on )SEAL command, 274 
space required, 224 
state indicator: Reset, 272 
State of shared variables: description of DSVS, 255 
State of the shared variables, 92 
State vector, 90 
state vector: point of view, 90 
reported by DSVS, 95 
table of possible values, 91 
when variable first shared, 87 
statement: Order in which functions and opera- 
tors executed, 21 
statement: Order of execution within line, 21 
statement: classes of things that may appear, 11 
distinguished from line, 17 
empty, 17 
reproduced in DER, 108 109 231 
statement being executed when event occurred: DER 
reproduces, 108 109 
Statements within the body of a line, 17 
status of current tasks: [RUNS reports, 198 
stile: to separate alternatives in sample system com- 
mands, 264 
STOP: event produced by stop control, 209 285 
Stop control, 208 
stop control: effect of copying or packing function 
in which stop or trace is set, 210 
event trapping may override, 209 
may be overridden by DTRAP, 117 
reserved prefix may not otherwise appear in a 
name, 39 
trappable event, 110 111 
storage charges: file, based on space actually used, 
101 
storage of diverse objects: package provides means, 
44 
storage space: data array, 288 
file component, 214 
not directly user’s concern, 37 
Storage space for objects in workspace: descrip- 
tion of 4 OWS, 228 
Storage space for value of shared variable, 98 
stored objects: must be named in workspace, 8 


string matching: use of A.=, 193 
strong interrupt: term used in APL Language, 55 
283 
structure and value of an array, 45 
Structure of a file, 99 
Structure of a package, 48 
Structure of array data, 44 
style: comparing “function” and “program,” 30 
Subscript: see “Index,” 155 
see “indexed assignment,” 170 
substitute symbols: QFMT, 203 
SUBTITLE: control message for HSPRINT subtitle, 
82 
Subtraction, 128 
subtraction: identity element, 187 
sum, Arithmetic, 128 
sum over: use of +/Y, 185 
Summary of forms in which operators, functions, 
and data may appear, 14 
Summary of line editing, 69 265 
suppression of unwanted output by use of DOUT, 80 
surrogate name: shared variable, 89 98 254 
suspended function: distinguished from pendent 
function, 41 226 
effect on line editing, 71 
resuming execution, 41 108 114 
SV INTERRUPT, 285 
trappable event, 111 
swap error: event reported in DER but not trappable, 
111 
SWAP ERROR, CLEAR WS, 285 
switching to another mode, 62 
Symbol: dual use, 19 
symbol: deciding whether it denotes a function or 
an operator, 22 
name by which known, 57 
to denote function or operator, 14 
to denote primitive function, 2 
used to represent primitive function, 12 
Symbol table: description of )SYMBOLS command, 
274 
symbol table: effect of unsuccessful attempt to use 
)COPY or )PCOPY, 267 
mechanism for noting referent of a name within 
a workspace, 37 
size and symbols in use reported by 2 [WS 3, 
227 
size following )CLEAR, 266 
space required, 224 
SYMBOL TABLE FULL, 285 
at load because of entry required for session vari- 


ables, 269 
distinguished from SYMBOL TABLE FULL ERROR, 
117 


following attempt to use )SYMBOLS command, 
274 
DFD condition, 207 
trappable event, 110 
SYMBOL TABLE FULL ERROR, 286 
not a trappable event, 117 
symbols in use: reported by 2 [WS 3, 274 
) SYMBOLS system command, 274 
symmetry of shared-variable relationship, 90 
synchronization of references to shared variables: ac- 
cess control permits, 92 


Syntax, 11 
syntax: defined function’s illustrated in header, 17 
34 


note regarding [ and M, 234 
operator unlike function, 13 
regularity of APL contrasted to conventional al- 
gebra, 23 
simplicity, 1 
SYNTAX ERROR, 286 
caused by branch statement in D input, 239 
example of error from ill-formed statement, 109 
trappable event, 110 
system: direct communication with (outside APL 
language), 10 
system and language are distinct, 2 10 
System command, 263 
system command: communication with system out- 
side APL langauge, 10 
compared with system function, 27 264 
excluded from argument of ¢, 171 
immediate execution mode required, 62 
response to request for [] input, 72 239 
trouble report, 278 
system error: effect on session variables, 249 
event reported in DER but not trappable, 111 232 
SYSTEM ERROR, CLEAR WS, 286 
System functions, 27 
see also chapters 21-32, devoted to system func- 


tions 
system functions: compared with system commands, 
27 40 264 


discussion and examples, 40 
for work with files, 9 
list, 28 
localization of not permitted, 38 
primitive denoted by [ followed by certain letters, 
25 27 
work with files requires permission in the file’s 
access matrix, 102 
system librarian: custodian of public workspaces, 9 
SYSTEM RESET DETECTED, 286 
system variable: copyable by commands )COPY and 
)PCOPY, 266 
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denoted by distinguished name, 40 

effects on environment of computation, 40 

list, 28 

localized during execution of a function, 35 38 42 
System variables and functions, 27 
System-default display, 52 
system-default display: evoked by Qe, 235 
system-picked width: dyadic ¥, 175 


T 


T: absolute reposition with DFMT, 202 
TA: prefix indicating trace control, 208 
TAB: representation in DARBIN input, 251 
terminal key, 55 251 
tab: counted as character during transmission, 223 
tab stops: index origin, 251 
setting, 251 
table: function, formed by outer product, 190 
table look-up: use of A.=, 193 
Take, 152 
take: figure to illustrate, 153 
fill elements, 153 
function that forms an array, 47 
when left argument specifies result with axes lon- 
ger than in right argument, 153 
tan: selected by left argument of 0, 136 137 
tanh: selected by left argument of 0, 136 
Task, 7 
task number: established at sign-on, 264 
reported by )PORT command, 271 
reported by 2 DWS 3, 227 
reported in DRUNS, 198 
required to use [JBOUNCE, 198 
to send terminal-to-terminal message, 269 271 
task owner, 7 
Task type: T-task, N-task, B-task, 7 
task type: reported by QRUNS, 198 
tasks: status of current, with DRUNS, 198 
telephone: access to network, 3 
ten: base of common number system, 160 
TEQ: definition of tolerant equality, 135 
)TERM system command, 274 
tabs during output, 252 
timing characteristics of terminal during display, 


54 
TERM workspace: types of terminals for )TERM com- 
mand, 274 


terminal: risk of damage from arbitrary output 
without adequate idles, 79 
site of interactive session, 4 
types for use with APL, 4 
video, 4 56 276 
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terminal: Background regarding transmissions to 
and from, 74 
terminal: Characters with special significance at, 
55 
terminal for use with APL, 2 
terminal input/output: System functions for, 234 
terminal output: append to file and/or display at 
terminal, 241 
captured with DOUT, 79 241 
terminal speed, 264 
terminal transmission codes: ASCII, BCD, and cor- 
respondence encodings, 54 
distinguished from internal representations of 
characters, 54 
explicit control, 55 
table, 75 
Terminal type: description of )TERM command, 274 
terminal type: indicated in sign-on, 264 
refined by use of )TERM command, 274 
terminal-task, 7 8 79 91 95 198 250 264 270 
terminal-to-terminal message, 269 
blocked by “no message” option, 268 
unaffected by DPW, 262 
Terse editing, 67 
text: in DFMT display, 202 
text delimiters: within left argument of QFMT, 202 
Thorn (dyadic): character representation of num- 
bers, 173 
Thorn (monadic): character representation of 
numbers, 172 
thorn (monadic): effect of DPW compared with its 
effect on default display, 262 
format numbers by system-default rules, 52 172 
tie number: file, 101 212 
not recorded in saved workspace, 273 
with use of OUT, 241 
tied file: name and number, 211 
time: CPU and connect, reported at sign-off, 270 
CPU and connect, reported by QRUNS, 198 
time and date: sign-on acknowledgement, 264 
time and date at which workspace was saved: fol- 
lowing DLOAD and )LOAD, 243 
time standard: see UTC 
time units: mixed-base number system, 160 
Times, 129 
times: identity element, 187 
timeshared APL: scheduling, 2 
Timestamp: description of DTS, 224 
timestamp: included in each component of a file, 9 
100 
showing when a file component was written, 214 
219 
showing when a workspace was saved, 227 


timing and width of [ display, 236 


TITLE: control message mnemonic for HSPRINT 
page title, 82 

tolerance: type conversion unrelated to comparison 
tolerance, 290 

tolerant equality: description, 122 135 

total number of elements in an array, 46 

ITPRINT: function for terminal display of QOUT file, 
81 

trace capability as part of trap line, 118 

Trace control, 208 

trace control: effect of copying or packing function 
in which stop or trace is set, 210 

reserved prefix may not otherwise appear in a 


name, 39 

trailing zeros: data entry and system-default dis- 
plays, 52 

transfer: data, between file and active workspace, 
100 


ownership of a file, 215 
transition diagram of SVS, 94 
transition table of [SVS, 93 
TRANSLATE: control message mnemonic for 
HSPRINT translate table, 82 
translation: input/output, reported by 2 [WS 3, 
227 
transmission codes: Explicit control, 55 234 
transmission codes: from terminal, recorded by arbi- 
trary input, 73 239 
to terminal, generated by arbitrary output, 239 
transmission control unit: APL system’s, 54 
messages not subject to event trapping, 107 277 
transmission of data: aided by minicomputers, 7 
transmission to and from terminal: Background 
regarding, 74 
transpose: function that forms an array, 47 
Transpose (dyadic): to permute or map together 
axes of an array, 145 
transpose (dyadic): figures illustrating, 147 
general formula for shape of result, 146 
Transpose (monadic): to reverse sequence of axes, 
144 
trap: Outline of facilities, 107 
trap definition: branch compared with branch in 
argument of ¢, 114 
cannot be in local QTRAP when you’re trapping 
return to immediate execution following 
normal exit, 115 
each must be well-formed, 112 232 
form, 111 232 
inadequate, causes return to immediate execution, 
110 232 
instruction within TRAP, 107 111 232 
possible actions, 113 232 
relevant, how the system locates, 112 


trap line: error, 112 
error in function invoked by, is trappable, 116 
error not trappable, 112 114 116 
execution compared with immediate execution of 
line from keyboard, 114 
field within trap definition, 111 113 232 
maximum length, 114 
reproduced in [ER if it invokes a function whose 
execution is aborted, 116 
tested by entering directly from keyboard, 118 
validity not checked, 233 
trappable errors and interrupts, 278 
trappable event: description, 106 
trappable events: evokable with SIGNAL, 110 
how handled when not trapped, 107 
list, 110 
trapping errors and interrupts, 5 
trapping not possible for certain events, 116 
tree diagram: to represent structure of an expres- 
sion, 19 
trigonometric functions, 135 
trouble report: source, 277 
true: result of Boolean function, 134 
truncation: high-precision representation of certain 
fractions, 53 
TS: timestamp functions, 219 227 
T-task, 7 
initiated by sign-on, 264 
interrupting shared variable delay, 95 
session and cumulative account information, 270 
sharing with other user’s, 91 
use of [OUT in conversion to N-task or B-task, 
79 
value of session variable at start, 250 
turn-around: Explicit control, 78 
Two types of array data, 47 
Two-pass line editing, 66 
tying a file, 101 212 
type: Internal, 288 
type: all elements of an array must be of same, 44 
argument’s, affects value supplied by expand, 158 
argument’s, affects value supplied by “over” take, 
153 
automatic conversion, 290 
internal, may be changed by indexed assignment 
of new values, 170 
numeric, never “equal” to character, 135 
type element: terminal using, 4 
type of an empty array, 47 
type of terminal: indicated in sign-on, 264 
types of array data, 47 
Types of statements, 18 
typewriter-like terminals: idles allow time for repo- 
sitioning typehead, 56 
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typewriter-pairing ASCII, 4 74 240 
reported by 2 [WS 3, 227 
TY33: reported by 2 (WS 3, 227 
TY33: argument or result of )TERM command, 274 
TY33 code, 74 


U 


UBS: upper-case backspace variable in workspace 
1 WSFNS, 56 
unaware of shared variable’s current value: which 
partner, 90 255 
undefined TRAP: system ignores, and searches more 
global OTRAP, 113 
unintended blank: inserted during line editing, 71 
union of sets: expression, 160 
unit circle: altitude, 137 
area of sector in circular functions, 137 
unit hyperbola: encloses area of sector, 137 
Universal application of order of execution, 23 
universal time: see UTC 
“unless”: effect of with conditional branch, 180 
unlocalized name: effect on 5 [WS, 229 
unlock keyboard: )KEYB system command, 268 
unmatched quotes: OPEN QUOTE message, 16 117 
DFD condition, 207 
unrecognized characters: entry or display, 54 
unresponsive terminal: avoid use of [TRAP that 
produces, 119 
Untie file, 213 
untie file: effect on file hold, 220 
untrappable events, 107 
unwanted output: suppressed by use of (OUT, 80 
update: saved workspace, 272 
Upgrade, 158 
upper case: how transmitted and represented from 
IBM-encoded terminals, 77 
upper-case backspace: character that can be dis- 
played but not entered, 56 60 
use: last two positions in state vector and access 
control, 90 255 
shared-variable, where set expected, 95 
term defined, and implication for shared varia- 
bles, 86 
Use of passnumbers, 103 
user input: protected from possible error or inter- 
rupt with QTRAP, 107 
User load: description of QUL, 224 
User-defined error, 117 
user-defined error: generated with DSIGNAL, 107 
233 
less than 1000, 109 
users: directory, 2 


347 INDEX 


UTC: result of OTS, 224 
sign-off acknowledgement, 270 
sign-on acknowledgement, 264 


V 


Valence of function, 19 25 
Valence of operator, 21 
Validate numeric input from characters: descrip- 
tion of DVI, 200 
validity: DTRAP not checked, 233 
Value: variable, description of 6 [WS, 229 
Value: variable in package, description of [IPVAL, 
247 
value: arguments of a function passed by, 19 35 
required in response to request for O input, 72 
shared variable’s may originate outside your ac- 
tive workspace, 85 
value and structure of an array, 45 
VALUE ERROR, 286 
arising from response to request for [0 input, 238 
example of event reflecting lack of needed object, 
109 170 
trappable event, 110 
value of shared variable: which partner knows, 255 
variable: class of use of a name, 223 224 229 245 
247 
created or given new value by assignment, 168 
local, representing argument of a function, re- 
ceives value when function executed, 43 
named collection of data, 13 37 245 
object within a package, 244 
value reported by 6 [WS, 229 
Variables list: description of )VARS, 268 
vector: array of rank 1, 45 
when formatted with [FMT appears as one-col- 
umn matrix, 201 
vector form of DTRAP, 111 
delimiter needed before each trap definition, 112 
vertical bar: to separate alternatives in sample sys- 
tem commands, 264 
video display unit: terminal using, 4 56 276 
Visible use of a name, 39 
visible use of a name: given functions currently in 
execution, 39 


WwW 


wait: see delay, 260 
weak interrupt: term used in APL Language, 55 
Well-formed name, 39 


well-formed name, 247 
well-formed QTRAP: criteria, 232 
When the result is displayed, 20 
WIDTH: control message mnemonic for OPW, 82 
width: field, in displays produced with dyadic ¥, 173 
174 176 
field, in system-default displays, how affected by 
OPP, 53 
field, insufficient, 178 
)WIDTH, former command, 264 
width and timing of [{ display, 236 
word length: transmission code, 239 
work: associated with account number of a user, 7 
Work area: description of [WA, 224 
work area: effect of indexed assignment, 170 
following )CLEAR, 266 
optimization of Boolean compressing iota vector, 
154 
Workspace, 8 
workspace: active, contents visible only to owner, 8 
active: where all calculation takes place, 6 
CONTINUE, 62 270 271 
dropped from auxiliary storage, 267 
environment in which names have meaning, 37 
load, 242 269 
locked, 226 242 266 269 272 273 276 287 
quota, 7 197 287 
saved: data usable only while in active workspace, 
6 
saved during [] input, 239 
sharing between two active, 91 254 
Workspace control information: description of 
2 [WS 4, 227 
Workspace environment: description of 2 [WS 3, 
227 
workspace environment: control by system variables, 
42 
workspace full: OFD error, 207 
see also WS FULL 
Workspace ID: description of 2 OWS, 226 
Workspace identification: description of )WSID 
command, 276 
Workspace information: description of OWS, 225 
Workspace information: system functions for re- 
porting, 222 
workspace name: field in ) LOAD command, 269 
field in argument of DLOAD or QQLOAD, 242 
field in )SAVE command, 272 
following )CLEAR, 266 
following load, 269 
reported or set by )WSID command, 276 
workspace password: following )CLEAR, 266 
set )SAVE or )WSID, 269 272 
workspace quota: required to use batch task, 197 


workspace saved at end of B-task: avoidable with 
OTRAP action D, 116 
workspace size, 8 266 
reported by 2 [WS 4, 227 
workspaces: list of those in user’s library, 268 
WS FULL, 286 
at load because of space required for QSP, 249 
269 
distinguished from WS FULL ERROR, 117 
following attempt to save active workspace, 98 
following attempt to use )COPY or )PCOPY com- 
mand, 267 
following attempt to use shared variable, 98 
message indicating lack of space in workspace, 37 
trappable event, 110 
WS FULL ERROR, 287 
example of event reflecting lack of space, 109 
not a trappable event, 117 
WS LOCKED, 287 
following attempt to use )COPY or )PCOPY com- 
mand, 267 
trappable event, 110 
WS NOT FOUND, 287 
following attempt to use )COPY or )PCOPY, 266 
267 
trappable event, 110 
WS NOT READABLE, 287 
trappable event, 110 
WS QUOTA USED UP, 287 
following attempt to use )SAVE command, 273 
)WSID: following )LOAD, 269 
)WSID system command, 276 
result of 2 DWS, 226 


x 


X: relative reposition with [JFMT, 202 


Y 


year: element of OTS, 224 


Z 


Z qualifier: to display leading zeros, 203 
zero: account number of workspace that has never 
been saved, 227 
branch to, special meaning during O input, 239 
branch to, special meaning within argument of 
2, 171 
default clone ID, 254 
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destination of branch, 179 

element of QLC, 223 

fill element for take and expand, 47 158 

first element of a radix, 162 

in representation that exceeds system’s precision, 
178 

leading, in DFMT display, 203 

leading and trailing, in character representations 
of numbers, 172 

left argument of QSVO indicates general offer, 86 

length of axis of reduction, 185 

passnumber for owner’s implicit access to file, 
103 

passnumber in file access matrix, 102 

representation in exponential format, 177 

represented by blank, 203 

system-picked width of ¥ display, 174 

timestamp of workspace that has never been 
saved, 227 

to indicate no connect or CPU limit on N-task, 
197 

user account number in file access matrix, 102 

value of DSC, 96 

value of DSVC when no clone ID established, 255 

zero divided by zero: definition in SHARP APL, 
129 
zero-origin: see index origin or [T0 
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